Retain strict three-host native qualification, discover fresh representative inventory automatically, and recheck deployed media before promotion. Document offline-only verification and outstanding field gates. Co-authored-by: GPT-6 <gpt-6@openai.com>
515 lines
33 KiB
Markdown
515 lines
33 KiB
Markdown
# Fresh managed-test target contract (isolated acceptance, not production approval)
|
||
|
||
## Autonomous three-CDN source candidate (2026-10-13): field acceptance pending
|
||
|
||
The user's three-CDN requirement is retained; the proposed single-CDN relaxation
|
||
was withdrawn. Service-mode discovery needs no manual domains: missing/empty
|
||
`ZAPRET_AUTOTUNE_GOOGLEVIDEO_VIDEO_IDS` uses primary `ZAPRET_AUTOTUNE_VIDEO_ID`
|
||
(default `dQw4w9WgXcQ`) plus `aqz-KE-bpKQ` and `jNQXAC9IVRw`, deduplicated.
|
||
A nonempty JSON array of 1..5 unique VideoIDs overrides this inventory. VideoIDs
|
||
are discovery inputs, not proof of distinct CDNs.
|
||
|
||
Fresh round-robin Player requests are bounded to three rounds (at most 15 requests)
|
||
and three minutes. Qualification selects three actual signed MP4 media hosts,
|
||
with at least two roots and two prefixes, and twenty-minute remaining URL TTL.
|
||
Only the existing version-1 owned native proof factory authorizes qualification:
|
||
post-warmup actual media 3/3 on both TLS protocols for each measured endpoint.
|
||
The common `googlevideo.com` suffix is an authorized extrapolative scope, not
|
||
measured evidence for every Googlevideo host or cold/uniform behavior.
|
||
|
||
Experimental promotion uses the same proof and fresh deployed three-host media
|
||
checks before committing apply. Insufficient inventory preserves the current
|
||
experiment and uses configured retry cooldown; genuine exhausted strategy search
|
||
still waits at least two hours. Qualified frontend is required; avatar success
|
||
does not block this media stage, but whole-service health remains DEGRADED until
|
||
actual avatar checks pass. Legacy service-off/exact-host behavior is unchanged.
|
||
|
||
This source candidate has only offline unit/fixture verification, not a newly
|
||
deployed image or field-qualified autonomous promotion. The 2026-10-12 measured
|
||
results below remain historical exact-endpoint evidence. Build from the committed
|
||
source archive and field-test the owned factory, three actual CDNs, deployed
|
||
relearning/apply, rollback and whole-service health before acceptance. Maximum
|
||
strategy collection and PID1 global-failure stay-alive remain unfinished future
|
||
increments. Arbitrary declarative service configuration is future work; no new
|
||
generic policy framework is supplied. See [GOOGLEVIDEO_DISCOVERY.md](GOOGLEVIDEO_DISCOVERY.md).
|
||
|
||
`managed init|reconcile|status|active-ids|apply` is exclusively for a **new dedicated container**
|
||
which owns its entire config. The existing/dev/production container must refuse
|
||
these commands. A role env or CLI-created identity is not enough. Provisioning
|
||
must supply all of the following before any managed command can run:
|
||
|
||
| Setting | Exact required value |
|
||
| --- | --- |
|
||
| `ZAPRET_AUTOTUNE_TARGET_ROLE` | `managed-test` |
|
||
| `ZAPRET_AUTOTUNE_TARGET_ID` | `zapret-autotune-managed-v1` |
|
||
| `ZAPRET_AUTOTUNE_TARGET_DIR` | `/var/lib/zapret-autotune/target` |
|
||
| `ZAPRET_CONFIG` | `/var/lib/zapret-autotune/target/config` |
|
||
| `SOCKS_PORT` | Base image's actual ss-local service port (canonical decimal, 1–65535) |
|
||
| `ZAPRET_AUTOTUNE_SOCKS_PROXY` | `socks5://127.0.0.1:$SOCKS_PORT` (expanded value) |
|
||
|
||
The fixed directory must already be a private runtime-user-owned **dedicated
|
||
persistent volume mountpoint**, not just a directory under another mount.
|
||
The production verifier checks the exact path in `/proc/self/mountinfo`.
|
||
Provisioning must also supply `/etc/zapret-autotune/target-id` containing exactly
|
||
`zapret-autotune-managed-v1` followed by a newline. Init never writes that marker.
|
||
Base runtime executables must exist: `/opt/zapret2/init.d/sysv/zapret2`,
|
||
`/opt/zapret2/nfq2/nfqws2`, and `/usr/bin/blockcheckw`.
|
||
There are no arbitrary directory flags or env overrides of these fixed values.
|
||
These are operator safety guards, not protection against a privileged user
|
||
deliberately forging a provisioned runtime.
|
||
|
||
The managed `config` is a standalone **full config only in this fresh volume**.
|
||
Never replace, adopt, or symlink over `/opt/zapret2/config` or any existing
|
||
service config. The deployment entrypoint must ensure the base daemon actually
|
||
honors the exact `ZAPRET_CONFIG` path; isolated RC acceptance does not waive
|
||
that check for a new image.
|
||
Existing services would require a separately designed managed **include
|
||
fragment**, not this full-config adapter. No such integration is implemented.
|
||
|
||
```sh
|
||
# Only after fresh-target provisioning establishes the entire contract above:
|
||
zapret-autotune managed init
|
||
zapret-autotune managed status
|
||
zapret-autotune managed apply --frontend-candidate 1 # bootstrap before discovery
|
||
zapret-autotune managed active-ids # JSON for supervisor; no health probe
|
||
zapret-autotune managed apply --frontend-candidate 1 --googlevideo-candidate 2
|
||
```
|
||
|
||
Init refuses nonempty directories except an exact private disabled baseline;
|
||
it never overwrites/adopts another config. It creates identity, journal and
|
||
backup; repeated initialization, symlinks, hardlinks, public/unowned files and
|
||
unsafe ancestors are refused. Status reports generation/hash/transaction state,
|
||
validated active IDs/groups and unresolved groups, not config, secrets or live
|
||
health. Pending or unverifiable state reports unknown groups and no active IDs;
|
||
drift fails closed. `active-ids` fails closed on pending or unverifiable state.
|
||
Init/status do not reload or probe, but both verify runtime and listener ownership.
|
||
|
||
All managed commands verify that the expected IPv4 listener is owned by a running
|
||
`ss-local` executable in the target PID/network namespace: `/proc/net/tcp` socket
|
||
inodes must match that process's file descriptors. A process alone, a wrong port,
|
||
or another loopback proxy is insufficient. Health repeats this validation before
|
||
its Player API request. The host's published SOCKS port may map to this listener,
|
||
but is never used inside the target. The standalone `health youtube` command
|
||
retains its separate generic loopback contract; managed activation is stricter.
|
||
Ambient proxies/direct fallback are disabled. Player API OK is **not playback**.
|
||
|
||
Apply accepts one or both frontend/exact-GGC SQLite candidate IDs, requiring
|
||
distinct positive IDs, at most one per group, complete endpoint × TLS evidence
|
||
and inert shell-safe arguments. The arguments are the full desired active set,
|
||
not patches: omitting a group removes it. Frontend-only bootstrap supports Player
|
||
API discovery before GGC scanning; GGC-only is also permitted. No missing profile
|
||
is invented, and missing groups remain unresolved. Player API OK never asserts
|
||
GGC/video playback or full-profile health. A supervisor can read `managed active-ids`
|
||
and explicitly retain the other group while replacing a failed one. It opens
|
||
the candidate DB read-only via `ZAPRET_AUTOTUNE_DB`; candidates are not active
|
||
state. Bindings/inputs are checked before pending transaction reconciliation.
|
||
Production reload is exclusively the fixed argv
|
||
`/opt/zapret2/init.d/sysv/zapret2 restart`, no shell, with a 30-second deadline.
|
||
Apply and rollback both use this full firewall/daemon restart; daemon-only
|
||
restart is not a supported fallback. This changes only the **new target
|
||
container's dedicated network namespace**, never the host or old container's
|
||
firewall. Provisioning must not use host networking or share an existing
|
||
container's network namespace.
|
||
|
||
The baseline explicitly sets `INIT_APPLY_FW=1`, `NFQWS2_ENABLE=0`, empty
|
||
`NFQWS2_OPT`, TCP ports `80,443`, UDP ports `443`, and TCP/UDP in/out packet
|
||
limits of `15`. QNUM is deliberately inherited from the base runtime default.
|
||
Active configs keep those fixed firewall values and set `NFQWS2_ENABLE=1`
|
||
with the qualified managed strategy arguments. Restoring the baseline and
|
||
running full restart removes its target-local queues and stops nfqws2;
|
||
restoring an earlier active config reinstates its firewall/daemon state.
|
||
The config replacement is atomic; the init script's stop/start sequence is
|
||
not a zero-interruption or kernel-atomic firewall transaction.
|
||
|
||
Journal v2 persists complete committed and pending candidate ID lists alongside
|
||
their hashes. Commit promotes the pending list; rollback/crash reconciliation
|
||
restores the prior list and hash. Reporting validates qualification/groups and
|
||
exact rendered hash against the read-only DB. Status reports invalid refs as
|
||
unresolved; `active-ids` and activation fail closed on invalid refs.
|
||
Legacy v1 journals keep the exact deployed hash and unknown IDs: status marks
|
||
both groups unresolved, and active-ids refuses to infer a list. A guarded full-set
|
||
apply upgrades to v2 only after the exact old hash matches; rollback preserves
|
||
the unknown legacy deployment. Re-init cannot adopt an existing deployment.
|
||
|
||
The transaction engine retains same-directory staging/fsync/rename,
|
||
durable journal/backup, advisory locking, external drift rejection, rollback
|
||
and fail-closed crash reconciliation. Failed rollback reload remains pending.
|
||
Directories must not be writable by untrusted processes; hostile concurrent
|
||
filesystem mutation is outside the transaction boundary. Shell config safety
|
||
and exact GGC filtering are unchanged.
|
||
|
||
The isolated [Compose definition](deploy/managed-target/README.md) supplies
|
||
the marker, mount and ordered startup; isolated deployments are recorded below.
|
||
No Docker socket, old target paths, Xray edits or host firewall provisioning
|
||
are included. Before each new deployment,
|
||
provisioning must verify the pinned image honors `ZAPRET_CONFIG`, supports all
|
||
listed variables, and starts ss-local while the baseline leaves nfqws2 disabled.
|
||
Start the fresh target with that baseline, then verify active apply installs
|
||
target-local nft NFQUEUE rules and starts nfqws2, and rollback restores both.
|
||
If any image/startup/routing requirement is unsupported or
|
||
uncertain, deployment must fail closed, not substitute `restart-daemons` or
|
||
alter an old config. Persistent volume durability is a provisioning
|
||
requirement; mountinfo alone cannot establish the storage lifecycle.
|
||
|
||
Internal `recoverManagedTarget` and `wireManagedRecovery` add injectable startup
|
||
bootstrap and saved-first recovery callbacks for the persisted monitor. Bootstrap
|
||
scans/checks/saves frontend and applies it alone with Player API post-check.
|
||
Recovery keeps an already healthy frontend, otherwise stops only the fixed
|
||
target zapret service, tries up to ten qualified saved IDs newest-first, and
|
||
scans only after complete valid non-pass results or health-rejected rollbacks.
|
||
Malformed reports/runner errors fail closed. GGC discovery uses the injected
|
||
managed-SOCKS path, revalidates against the fresh exact host, and saves new
|
||
immutable evidence before full-set apply. A frontend-only rollback boundary
|
||
survives GGC failure; unresolved GGC is reported separately, not playback health.
|
||
Cancelled/failed downtime restores the committed configuration and runs fixed
|
||
target `start` with an independent 30-second cleanup deadline. Failed cleanup or
|
||
rollback is fatal to the supervisor; unresolved journal state is never started.
|
||
The callback caller must hold the monitor singleton; the wiring repeats runtime
|
||
identity/SOCKS guards. `managed monitor` binds those callbacks and only the
|
||
dedicated target entrypoint starts it; local and isolated runtime validation
|
||
results, with their limits, are recorded in [PROGRESS.md](PROGRESS.md).
|
||
|
||
## Dedicated monitor integration (isolated clean-run acceptance passed)
|
||
|
||
`zapret-autotune managed monitor [--interval 5m] [--failure-threshold 3]
|
||
[--cooldown 30m]` uses the health environment defaults. Interval is positive and
|
||
at most 24h, threshold 1–1000, cooldown positive and at most 168h; explicit empty
|
||
or invalid settings fail before any lock. No executable/path/proxy flags exist.
|
||
The DB environment must be exactly `/var/lib/zapret-autotune/target/candidates.db`;
|
||
existing DB/sidecars must be private, owned regular files without aliases/hard links.
|
||
Runtime/SOCKS, directory, identity and DB path guards run before the singleton.
|
||
SQLite opens writable target-owned state; active IDs remain journal/DB/hash validated.
|
||
|
||
Probe reuses `health youtube`'s Player API contract, forced owned loopback SOCKS,
|
||
no direct fallback. Discovery uses that same SOCKS adapter. Scan/check execute
|
||
only `/usr/bin/blockcheckw`, daemon operations only fixed target-local
|
||
`/opt/zapret2/init.d/sysv/zapret2` start/stop/restart argv; no shell/eval command
|
||
strings. Context cancellation kills/waits process groups and bounded restoration
|
||
finishes before returning. Reports suppress untrusted diagnostics and credentials.
|
||
|
||
Startup reconciles transactions under the singleton and bootstraps only when no
|
||
qualified active frontend exists. Bootstrap/recovery checks saved candidates first;
|
||
GGCError reports unresolved and continues probing, not playback success. Other
|
||
DB/safety/journal/runner failures stop nonzero; joined cancellation plus a cleanup
|
||
failure is also fatal. A qualified frontend at startup is probed immediately,
|
||
not rescanned merely because the process restarted.
|
||
|
||
Entrypoint ordering is SS children → listener → fresh managed init if needed → managed reconcile → zapret start
|
||
→ one installed `/usr/local/bin/zapret-autotune managed monitor` child. It supervises
|
||
all three children; unexpected monitor exit is not a successful shutdown.
|
||
SIGTERM/SIGINT cancels and waits the monitor before target-local zapret stop and
|
||
SS child termination/wait. Existing targets and Xray remain unchanged. Deployment
|
||
allows 240s Compose shutdown grace for bounded
|
||
monitor cancellation/restoration and child joins. Clean RC `d8316e6` has passed
|
||
isolated image/routing, bootstrap, periodic probe, monitor-crash cleanup, graceful
|
||
stop and persistent recreation gates; see the
|
||
[recorded source/image and PASS report](deploy/managed-target/README.md#recorded-clean-run-acceptance-2026-10-11-pass).
|
||
This does not establish playback or blanket production approval.
|
||
|
||
Injected unit tests cover exact identity/path/config, mountpoint refusal,
|
||
old-container-like env, SOCKS port/process refusal, correct fresh-target success,
|
||
non-overwrite, transaction rollback and redaction. Verification results are
|
||
recorded in [PROGRESS.md](PROGRESS.md). Focused local checks can be rerun with:
|
||
|
||
```sh
|
||
go test ./cmd/zapret-autotune -run TestManaged
|
||
go build ./cmd/zapret-autotune
|
||
```
|
||
|
||
## Production preparation
|
||
|
||
This is a standalone **new isolated target** candidate, not a production-approved
|
||
deployment and not an integration into existing zapret/Xray. Keep the exact
|
||
`managed-test` role, ID, marker, mount, config, DB and owned-listener guards above.
|
||
Do not change the role to `production`, adopt old state, share an old network
|
||
namespace, or relax a refusal. Container provisioning instructions
|
||
are described in [deploy/managed-target/README.md](deploy/managed-target/README.md).
|
||
|
||
### Build once, promote the same image
|
||
|
||
Use `Dockerfile.target` for the supervised target; root `Dockerfile` is the
|
||
proposal CLI image, not the managed service. Both pin Go 1.25.3 and the runtime
|
||
by digest, use `GOTOOLCHAIN=local`, `CGO_ENABLED=0`, `go.sum`, and `-trimpath`.
|
||
Pins constrain build inputs; they do not establish live acceptance or guarantee
|
||
bit-for-bit builds on different platforms. Record the source commit, platform,
|
||
builder/runtime digests and resulting image digest for every release.
|
||
|
||
Both Dockerfiles require BuildKit for the compilation-cache mount at
|
||
`/root/.cache/go-build` (enable with `DOCKER_BUILDKIT=1` if not already default).
|
||
This cache only speeds rebuilds; it is not copied into the final runtime image
|
||
and is not a secret store. No deployment credentials are needed or passed to
|
||
the build; keep secrets out of build arguments and cache contents.
|
||
|
||
Example (replace registry and release; never reuse a release tag):
|
||
|
||
```sh
|
||
IMAGE=registry.example/team/zapret-autotune-managed-target:2026-10-10-r1
|
||
docker build --pull -f Dockerfile.target -t "$IMAGE" .
|
||
test "$(docker image inspect --format '{{json .Config.Entrypoint}}' "$IMAGE")" = '["/bin/sh","/opt/managed-target-entrypoint.sh"]'
|
||
docker run --rm --network none --entrypoint /bin/sh "$IMAGE" -ec 'test "$(cat /etc/zapret-autotune/target-id)" = zapret-autotune-managed-v1; test -f /opt/managed-target-entrypoint.sh'
|
||
docker push "$IMAGE"
|
||
docker image inspect --format '{{index .RepoDigests 0}}' "$IMAGE"
|
||
```
|
||
|
||
Promote the printed `registry/repository@sha256:...` reference unchanged from
|
||
validation to deployment; do not rebuild or use `latest`. Authenticate separately,
|
||
never put registry credentials in these commands. The supplied Compose file
|
||
selects `${ZAPRET_AUTOTUNE_IMAGE:-zapret-autotune-managed-target:local}`. Set
|
||
`ZAPRET_AUTOTUNE_IMAGE=registry.example/team/zapret-autotune-managed-target@sha256:<digest>`
|
||
in the same private deployment `.env` as `SS_PASSWORD` (mode `0600`), using the
|
||
actual printed digest. Tags and the local default are build/test candidates only;
|
||
an immutable managed-target digest is required for production promotion. From
|
||
the repository root, validate and pull without printing the rendered secrets:
|
||
|
||
```sh
|
||
docker compose --env-file deploy/managed-target/.env -f deploy/managed-target/compose.yaml config --quiet
|
||
docker compose --env-file deploy/managed-target/.env -f deploy/managed-target/compose.yaml pull target
|
||
```
|
||
|
||
Do not omit `-f Dockerfile.target`: root `Dockerfile` builds the proposal/prototype,
|
||
not the PID-1-managed target. Assert both entrypoint and provisioned marker on the
|
||
exact selected image before promotion; the assertions above are image-contract
|
||
checks, not live resource qualification. A managed-looking tag is insufficient.
|
||
|
||
Start the selected container image with Compose `up --no-build`;
|
||
no host service installation is required. Keep the selected digest and
|
||
private configuration together for upgrades and rollback. Never run a build
|
||
against the production digest selector; build/tag separately as shown above.
|
||
|
||
### Configuration and secrets
|
||
|
||
Create fresh empty `target-state` owned by root/runtime UID 0, mode `0700`, and
|
||
the private deployment `.env` mode `0600`; rootless/remapped Docker needs the
|
||
mapped owner. Bootstrap is for empty provisioned state only; recreation retains
|
||
identity, journal, candidate DB, sidecars and lock file. Never automatically wipe
|
||
state to make startup succeed. The entrypoint creates Shadowsocks JSON in private
|
||
tmpfs (`0700` directory, `0600` files), unsets the password before children, and
|
||
does not put it in argv. Docker administrators/root can still read container env
|
||
and runtime config. Do not print `.env`, rendered Compose config, diagnostics or
|
||
signed URLs; use `docker compose ... config --quiet` for validation.
|
||
|
||
| Existing setting | Default / accepted value for managed target |
|
||
| --- | --- |
|
||
| `ZAPRET_AUTOTUNE_IMAGE` | Local build/test default `zapret-autotune-managed-target:local`; production promotion requires a managed-target `repository@sha256:<digest>` |
|
||
| `SS_PASSWORD` | Required independent hex-only secret, at least 32 characters; deployment README generates 64 |
|
||
| `SS_DNS_SERVER` | Empty (unchanged resolver); optional literal IPv4/IPv6 for target-only native ss-server DNS, validated before launch |
|
||
| `ZAPRET_AUTOTUNE_YOUTUBE_SERVICE` | `0` (legacy) or opt-in `1`; explicitly forwarded by Compose |
|
||
| `ZAPRET_AUTOTUNE_GOOGLEVIDEO_MODE` | `cold` default or `adaptive` (requires service `1`); explicitly forwarded |
|
||
| `ZAPRET_AUTOTUNE_GOOGLEVIDEO_VIDEO_IDS` | JSON array of 1..5 unique VideoIDs; defaults to only the primary ID; explicitly forwarded |
|
||
| `ZAPRET_AUTOTUNE_HOST_SOCKS_PORT` | `11080`; choose an available TCP/UDP port 1–65535, published only on `127.0.0.1` |
|
||
| `SOCKS_PORT` | Supplied deployment fixes internal listener to `1080`; not a host-port override |
|
||
| `ZAPRET_AUTOTUNE_SOCKS_PROXY` | Fixed `socks5h://127.0.0.1:1080` inside this target, no credentials/direct fallback |
|
||
| `ZAPRET_AUTOTUNE_VIDEO_ID` | `dQw4w9WgXcQ`; exactly 11 ASCII letters, digits, `_` or `-` |
|
||
| `ZAPRET_AUTOTUNE_HEALTH_INTERVAL` | `5m`; duration in `(0,24h]` for monitor |
|
||
| `ZAPRET_AUTOTUNE_FAILURE_THRESHOLD` | `3`; integer 1–1000 for monitor |
|
||
| `ZAPRET_AUTOTUNE_RECOVERY_COOLDOWN` | `30m`; duration in `(0,168h]` for monitor |
|
||
| `ZAPRET_AUTOTUNE_DB` | Fixed `/var/lib/zapret-autotune/target/candidates.db` |
|
||
|
||
Managed Player, metadata, image, media and warmup requests send hostnames through
|
||
the owned SS listener (`socks5h`), so they respect target-native DNS instead of
|
||
bypassing it with curl's local resolution. Older private environment overrides
|
||
using `socks5` are canonicalized internally after validation; arbitrary proxies
|
||
remain rejected by the listener/port/process ownership guard. Legacy public CLI
|
||
discovery and root checker `--resolve` pinning are unchanged. This corrects a DNS
|
||
path bypass, not a proven explanation of earlier peer certificate failures.
|
||
|
||
The monitor's three policy flags override corresponding environment defaults;
|
||
explicit empty/invalid environment settings are rejected. The entrypoint accepts
|
||
no arguments. Compose forwards the primary/sample VideoIDs and service/mode settings.
|
||
It does not forward the interval/threshold/cooldown policy
|
||
settings from `.env`: add those existing variables to `target.environment`
|
||
in your deployment copy/override if needed. Keep all fixed identity/path settings
|
||
unchanged. No public SS listener is published; Xray configuration is external and
|
||
operator-owned, optionally using the host's loopback SOCKS port. Do not modify an
|
||
existing Xray deployment as part of bootstrap.
|
||
|
||
Current service/adaptive hardware acceptance is **pending**, independent of the
|
||
recorded legacy RC PASS. Adaptive means post-warmup, not cold: first connections
|
||
may fail and native learning repeats after restart. At least three real unique
|
||
signed ordinary media host samples are required; multiple VideoIDs may yield one
|
||
CDN host and leave `DEGRADED` with no authorized suffix. Sampled thumbnail/avatar
|
||
routes do not prove availability of the whole thumbnail pool. The reported
|
||
`8.8.8.8` DNS diagnostic corrected a tampered avatar, not all thumbnail routes;
|
||
native DNS correction is not full asset availability proof. Target DNS uses
|
||
validated native `-d` argv (nonsecret), with installed-option support checked
|
||
at image build; passwords remain private JSON only. No DoH bridge, permanent
|
||
Google IP pins, global host DNS edits or external startup manager are introduced.
|
||
|
||
### Supervision and failure handling
|
||
|
||
The container entrypoint is PID 1 and owns all technical child restart control.
|
||
After a retryable monitor/SS failure it joins children, reconciles trusted state
|
||
and stops target-local zapret before starting a new runtime cycle in the **same
|
||
container**. Retries use cancellable backoff (15s, 30s, capped at 60s) and at most
|
||
three runtime starts per rolling six hours, including the initial start. Exhaustion
|
||
stops fail-closed with 78; configuration, safety, DB, journal, rollback or cleanup
|
||
errors never authorize retry. No new dependency, host service installation or
|
||
external process manager is required. SIGTERM/SIGINT cancels backoff or the running
|
||
monitor, waits for bounded restoration and joins children before exit.
|
||
|
||
Compose restart remains disabled: a blanket container restart could loop over a
|
||
safety refusal or reset the in-container retry budget. Compose stop grace is 240s:
|
||
the sequential cleanup budget is 140s (45s monitor join, 45s reconciliation plus
|
||
5s kill grace, 30s zapret stop plus 5s kill grace, and two 5s SS joins), with room
|
||
for a deferred 45s startup command plus kill grace and scheduling overhead.
|
||
The join watchdog runs in a fresh shell and is cancelled when its child finishes;
|
||
graceful shutdown does not wait out the watchdog's full deadline.
|
||
Container-platform lifecycle, creation/recreation and host-boot policy belong to
|
||
the deployment operator, not an external manager supplied by this project.
|
||
|
||
| Target exit | Operator meaning |
|
||
| --- | --- |
|
||
| `64` | Invalid configuration; fix settings before starting |
|
||
| `78` | Safety/DB/journal/rollback/cleanup failure; investigate, no automatic restart |
|
||
| `75` | Internal technical-cycle result; PID 1 retries only after safe cleanup, within its budget |
|
||
| `0` | Graceful signal shutdown; no automatic restart |
|
||
|
||
Bootstrap/recovery has a fixed **90-minute whole-job deadline**, plus an
|
||
independent **30-second restoration reserve**. This is a catastrophic technical
|
||
ceiling, not a normal candidate-check timeout and not an operator tunable. Valid
|
||
nonpassing candidates/unresolved GGC are normal recovery outcomes, not a reason
|
||
to restart the container. Genuine **no qualified strategy** from validated scan/check
|
||
evidence persists a recovery wait of at least **two hours** in SQLite, including
|
||
empty bootstrap and frontend/GGC exhaustion. The same container stays alive and
|
||
continues light periodic Player API probes; it does not scan or apply during that
|
||
wait. Startup respects the durable expiry, and recovery resumes after expiry under
|
||
the normal failure-threshold policy. In both fresh bootstrap and periodic recovery,
|
||
the delay is the greater of two hours and the configured recovery cooldown;
|
||
a longer configured cooldown is not shortened.
|
||
Other ordinary recovery outcomes retain the configured cooldown (default **30m**).
|
||
Malformed/incomplete reports, runner errors and unsafe state are not strategy
|
||
absence and must not enter this wait. The two-hour minimum absence policy is not a
|
||
new operator setting, technical retry backoff, or the **90-minute watchdog**. Failed
|
||
restoration or unsafe state vetoes retry: timeout exit 75 requires the job's own
|
||
deadline and only timeout/cancellation-related errors, with no joined cleanup,
|
||
DB or safety failure. Unexpected monitor/SS failures are separately technical
|
||
only if shutdown cleanup succeeds. Shutdown uses bounded monitor join,
|
||
guarded reconciliation, target-local zapret stop and SS child joins;
|
||
failure to join/restore is fail-closed. The reserve is not extra
|
||
scanning time. The 90-minute budget is shared by the whole bootstrap/recovery
|
||
job, not renewed per candidate or phase.
|
||
|
||
Monitor health means Player API `OK` through owned SOCKS. GGC evidence covers
|
||
only the **exact discovered hostname** and tested TLS protocols, not wildcard
|
||
googlevideo coverage, video transfer, SABR or playback. Unresolved GGC must not
|
||
be reported as complete playback health.
|
||
|
||
### Upgrade, rollback and operator recovery
|
||
|
||
1. Record the current image digest and private deployment configuration. Stop
|
||
the target with Compose, wait for complete cleanup, and verify
|
||
the target is stopped. If cleanup fails, investigate before upgrading.
|
||
2. With the target stopped, make a root-only backup of the **entire** state
|
||
directory (including DB sidecars, journal, config, identity and lock file),
|
||
preserving ownership/modes. Store `.env` and image/config records privately
|
||
with it; do not print archive contents, diagnostics or signed URLs. A live
|
||
copy of only `candidates.db` is not a consistent rollback backup.
|
||
3. Select/pull the new immutable digest and start without building. Inspect
|
||
sanitized status/logs, verify identity/hash and expected active groups, owned
|
||
SOCKS, target-local queues, health scope and persistent recreation. Keep the
|
||
old image and backup until acceptance; DB migrations may prevent image-only
|
||
downgrade.
|
||
4. To roll back, stop and verify cleanup again. Preserve failed state separately
|
||
for investigation. Restore the matched stopped-state backup **as a whole**
|
||
into the same dedicated mount with private ownership/modes, select its old
|
||
digest/config, then start. Do not merge journals/DB generations or re-init.
|
||
A restored legacy/live/unverifiable recovery owner can fail closed; never
|
||
clear its lease or unlink the lock merely to force startup.
|
||
|
||
On startup, `managed reconcile` accepts no flags and uses only the fixed private
|
||
`/var/lib/zapret-autotune/target/candidates.db`. Known interrupted prepared state
|
||
is rolled back to qualified committed bytes before any reload/start; fresh
|
||
baseline and known committed state are idempotent. Unknown/legacy state, drift,
|
||
missing qualification or failed rollback blocks startup with a non-retry exit.
|
||
|
||
On drift, unreconcilable pending transaction, rollback failure, or exhausted PID 1 retry
|
||
budget, leave state intact and the container stopped. Diagnose using sanitized status
|
||
and private artifacts; repair the actual provisioning/configuration issue or
|
||
restore a known consistent backup. Only then manually start the target with Compose.
|
||
There is no automatic wipe or
|
||
automatic adoption path.
|
||
|
||
The recorded clean RC PASS covers empty-state bootstrap through qualified frontend
|
||
and exact-host GGC apply, image/config binding, ongoing probes, in-container monitor
|
||
crash restart, graceful stop and persistent recreation. Earlier recovery, rollback,
|
||
rotation, retry and absence fixtures are distinguished in [PROGRESS.md](PROGRESS.md);
|
||
do not attribute all of them to the clean run. No media playback, real 90-minute
|
||
watchdog expiry or real two-hour absence expiry wait is claimed. Production rollout
|
||
and backup-restore acceptance remain operator gates on a new isolated target;
|
||
local unit/static checks and isolated PASS do not establish blanket production readiness.
|
||
|
||
### Explicit experimental Googlevideo suffix
|
||
|
||
Normal `--googlevideo-scope suffix` still requires representative qualification,
|
||
media proof, and both qualified image profiles. An operator may explicitly own
|
||
the audited native circular A/E composite without claiming those results:
|
||
|
||
```sh
|
||
zapret-autotune managed apply --googlevideo-experiment native-circular --googlevideo-scope experimental_googlevideo_suffix
|
||
```
|
||
|
||
This command requires the monitor singleton to be free, a matching native Lua
|
||
hash, a fresh Player-discovered exact GGC identity, and existing qualified
|
||
frontend/assets. It preserves their candidate IDs and uses the normal guarded
|
||
transaction/reload/Player-health/rollback hooks. The new candidate definition
|
||
has no cold/adaptive evidence and is not a qualified candidate. Both pending
|
||
and committed journal policy record `experimental_googlevideo_suffix`; legacy
|
||
rendered bytes and qualification gates are unchanged. Unknown policies fail closed.
|
||
|
||
For PID-1-controlled application, while this dedicated target is stopped and
|
||
after taking a complete private state backup, create a private empty file named
|
||
`.autotune-experimental-suffix-request` in its owned state directory. It must be
|
||
an empty regular 0600 file owned by the runtime UID, with no symlink/hardlink.
|
||
Startup validates it before init/reconcile, then atomically claims the validated
|
||
inode before guarded apply (before launching the monitor). Only a successful
|
||
apply removes that claim; a replacement request is never deleted. Failure exits
|
||
closed and retains the private `.autotune-experimental-request-claim-*` artifact;
|
||
do not blindly retry it. Use the matched whole-state/image rollback above.
|
||
Candidate-ID CLI apply cannot select/inherit the experimental policy; explicit
|
||
native-circular authorization is required. Internal journal recovery is unchanged.
|
||
|
||
Resource probes still run. In service mode (legacy or adaptive), healthy actual
|
||
image/media probes short-circuit recovery, but operational health does not mean
|
||
family qualification or playback READY. Experimental media recovery preserves
|
||
the operator suffix and all committed profile IDs: a validated transfer failure
|
||
permits one guarded restart of that same deployed daemon, then at most 10 native
|
||
relearning attempts within 120s and a final fresh signed media 3/3 for each of
|
||
TLS1.2 and TLS1.3. Learning stays in the persistent daemon's RAM; no temporary
|
||
NFQ worker or replacement/qualified candidate is created. Expiring media is
|
||
rediscovered, never rewritten or persisted. Missing inventory remains degraded,
|
||
not strategy absence; mixed, guard, infrastructure and cancellation errors do
|
||
not authorize relearning. Unrelated missing image inventory may coexist with
|
||
usable media, but successful media recovery does not repair or qualify it.
|
||
|
||
Avatar inventory first parses fresh homepage `ytInitialData`. Only absent metadata
|
||
or no allowed avatar permits one fallback to the configured video's watch page,
|
||
using a validated video ID, the same trusted HTTPS WWW origin and SOCKS proxy,
|
||
bounded time/body size, no redirects, and discarded diagnostics. Malformed JSON,
|
||
transfer errors and safety/cancellation failures do not trigger fallback. Both
|
||
pages and discovered resource URLs remain ephemeral; discovering an allowed URL
|
||
is not image-transfer qualification or a guarantee of full-family coverage.
|
||
|
||
`managed status` reports active-profile `covered=` separately from qualified
|
||
`groups` and `unresolved_groups`; `managed active-ids` adds `covered_groups` and
|
||
`googlevideo_scope` to its JSON. An experimental Googlevideo profile can be
|
||
covered yet qualification-unresolved; one image profile does not establish full
|
||
asset-inventory success. Status is read-only and reports live health NOT CHECKED.
|
||
Historical `a60f62d` restart/recreation and status checks passed, but its upgrade
|
||
hit `BrokenPipe` and rolled back; that run did not accept media recovery. Later
|
||
supplied final field results for source `fd25cb8`, managed image
|
||
`sha256:73e955e7fdc6efaef88c62ebe4f7afeab71c29d29ba3c88b2a2b7547bb647da5`
|
||
on SOCKS11082 completed a 15-minute watch with restart count0 and a live monitor.
|
||
Validated rejection/no-qualified-strategy recovery continued with naturally
|
||
advanced cooldown and unchanged experimental profiles; it did not repair avatars.
|
||
Three fresh media hosts across two roots passed post-warmup 3/3 on each TLS
|
||
protocol (18 actual HTTP206/65536-byte MP4 transfers). This is field evidence,
|
||
not persisted family qualification, a cold/all-host claim or candidate promotion.
|
||
Watch fallback discovered allowed avatar metadata, but both-TLS curl28 transfers
|
||
had zero samples: avatar evidence/profile qualification is still absent and
|
||
overall health is **DEGRADED / NOT READY**. Automatic durable multi-host family
|
||
qualification remains unimplemented. See [PROGRESS.md](PROGRESS.md) for exact
|
||
hosts, separate warmup results, timestamps, private proof and remaining gates.
|
||
No new network checks accompany this documentation. Generic production
|
||
media behavior and signed-URL/SS secret privacy remain unchanged, as do the
|
||
persisted minimum two-hour strategy-absence pause and 90-minute whole-job budget.
|