vmess-domain-rotator/workflow.md

Workflow

1. Server Mode

flowchart TD
    A1[systemd timer / manual run] --> A2[run_update_and_commit.sh config.server.json]
    A3[manual updater run] --> A4[domain_updater.py --config config.server.json]

    subgraph U1["domain_updater.py / server mode"]
      direction TB
      B1[read config.server.json] --> B2[resolve output paths]
      B2 --> B3[read runtime/state.json]
      B3 --> B4[fetch API payload]
      B4 --> B5[parse candidates]
      B5 --> B6[apply domain filter]
      B6 --> B7[apply record filter]
      B7 --> B8[score and rank]
      B8 --> B9[select preferred domain]
      B9 --> B10[build top_candidates (sparse fields, unified semantics)]
      B10 --> B11[write runtime/current_domain.txt]
      B11 --> B12[write runtime/current_domain.json]
      B12 --> B13[write runtime/substore_vars.json]
      B13 --> B14[write runtime/state.json]
    end

    A2 --> C1[resolve configured output paths]
    C1 --> A4
    A4 --> C2[capture updater JSON output]
    C2 --> C3[detect status: error_use_last_good?]
    C3 --> C4[read selected text file from resolved path]
    C4 --> C5[compare with runtime-state HEAD]
    C5 --> C6{changed?}
    C6 -- no --> C7[skip commit/push]
    C6 -- yes --> C8[sync configured repo-local output files]
    C8 --> C9["commit on runtime-state<br/>(chore: or chore(fallback):)"]
    C9 --> C10[optional push]

2. Local Python cfst Mode

flowchart TD
    A1[manual run] --> A2[domain_updater.py --config config.local.json]

    subgraph U2["domain_updater.py / cfst_local mode"]
      direction TB
      B1[read config.local.json] --> B2[resolve output paths]
      B2 --> B3[run local cfst]
      B3 --> B4[parse result.csv]
      B4 --> B5[apply domain filter]
      B5 --> B6[select preferred ip]
      B6 --> B7[build top_candidates (sparse fields, unified semantics)]
      B7 --> B8[write configured current_ip.txt]
      B8 --> B9[write configured current_ip.json]
      B9 --> B10[write configured substore_vars.json]
      B10 --> B11[write configured state.json]
    end

3. BusyBox Router Mode

flowchart TD
    A1[crond / manual run] --> A2[router_local_update.sh config_router.conf]
    A3[background service / manual run] --> A4[router_local_http.sh config_router.conf]

    subgraph R1["router_local_update.sh"]
      direction TB
      B1[read config_router.conf] --> B2[run cfst]
      B2 --> B3[read result.csv]
      B3 --> B4[pick best ip]
      B4 --> B5[write configured current_ip.txt]
      B5 --> B6[write configured current_ip.json]
      B6 --> B7[write configured substore_vars.json]
      B7 --> B8[write configured state.json]
    end

    subgraph R2["router_local_http.sh"]
      direction TB
      C1[read config_router.conf] --> C2[start configured BusyBox httpd]
      C2 --> C3[serve current_ip.txt]
      C2 --> C4[serve current_ip.json]
      C2 --> C5[serve state.json]
      C2 --> C6[serve substore_vars.json]
    end

4. Error / Fallback Flow

flowchart TD
    A1[updater encounters error] --> A2{last_good value exists?}
    A2 -- no --> A3[exit with error]
    A2 -- yes --> A4[write last_good to selected text file]
    A4 --> A5["write selected JSON<br/>(status: error_use_last_good)"]
    A5 --> A6["write vars file<br/>(STATUS: error_use_last_good)"]
    A6 --> A7[write state.json with error]
    A7 --> A8[run notify command]
    A8 --> A9["output JSON to stdout<br/>(status: error_use_last_good)"]
    A9 --> A10["run_update_and_commit.sh detects fallback status"]
    A10 --> A11["commit with chore(fallback): prefix"]

5. Consumers

flowchart TD
    A1[runtime/current_domain.json] --> B1[Sub-Store operator]
    A2[cfip_runtime/current_ip.json over LAN] --> B1
    B1 --> C1["cache lookup<br/>(key scoped per VALUE_SOURCE_MODE)"]
    C1 --> C2{cache hit?}
    C2 -- yes --> C3[use cached value]
    C2 -- no --> C4[fetch and decide by mode]
    C4 --> C5[read domain or ip]
    C3 --> C6[rewrite matched proxy server]
    C5 --> C6