feat: runtime config management API + supporting backend work

[roziscoding]

Context

Adds a runtime config management API so peers, servers, and settings can be managed live (no restart), plus the supporting backend work this branch accumulated. jack's config stays a hand-editable, version-controllable config.jsonc (the file is the source of truth) — the management API mutates it through a single serialized writer and applies changes to the live connector map.

What's included

Config management API (the main deliverable)

• A separate management surface on its own port (getManagementApp + a 2nd Bun.serve on MANAGEMENT_PORT), guarded by X-Management-Key (constant-time compare), started only when MANAGEMENT_KEY is set. The public peer port never exposes /config.
• ConfigService: one in-process serialized write queue; rollback-safe atomic file writes (tmp→rename, randomized temp name, preserved perms); persists the raw config so {env}/{file} secret refs are never resolved into the file.
• Live peers CRUD: add / remove (disable-as-soft-delete, in-flight drains) / rename / URL-change rekey with a peer_id download cascade.
• Live servers CRUD (+ source/destination list reconciliation).
• Live connector visibility: search fan-out (/torznab, /peer, /items, /servers, qB) reads connectors live, so add/remove is searchable without restart.
• Migration write-back: a migrated config is persisted with a .bak; also fixes a pre-existing crash where an up-to-date config failed to parse on the next boot.

Supporting backend work (earlier commits on this branch)

• Sensitive-field redaction in logs + a span-attribute redacting funnel.
• Versioned config migration system; TypeScript 6 bump (noUnusedLocals/Parameters).
• Connector-lifecycle refactor (decorator rename; ConnectorManager-shaped deps).

Notes

• No UI yet — the management API is the backend foundation; UI/CLI/BFF are out of scope.
• MANAGEMENT_KEY is operator-set via env (no first-boot key generation).

Testing

• bun test: 223 pass / 0 fail · tsc --noEmit: clean · eslint .: clean

Greptile Summary

This PR delivers a runtime config management API on a separate, key-guarded port plus the supporting backend work accumulated on the branch (migration system, connector-lifecycle refactor, span-attribute redaction funnel, TypeScript 6 upgrade). The config.jsonc file remains the source of truth; mutations flow through a serialized write queue with rollback-safe atomic writes and preserve {env}/{file} secret references verbatim.

• Config management API: A second Bun.serve on MANAGEMENT_PORT (default 5226), guarded by SHA-256 constant-time X-Management-Key compare; full peers/servers CRUD with live ConnectorManager reconciliation, download-row cascade on peer URL rekey, and soft-delete drain semantics.
• Migration system: Versioned migrations run on boot, back up the original file, and atomically rewrite the upgraded config; also fixes the prior crash where an already-current config failed to parse on re-boot.
• Span-attribute redaction: A single setSpanAttribute/setSpanAttributes funnel in span-attributes.ts replaces scattered direct span.setAttribute calls, enforcing redaction and 8 KB truncation uniformly.

Confidence Score: 5/5

Safe to merge — the management API is well-isolated on its own port, file writes are atomic and rollback-safe, and the serialized write queue prevents concurrent mutation races.

The rollback-safe persist-then-commit ordering in ConfigService, idempotent init() guard in ServerConnector, constant-time key comparison, and migration backup all work correctly. No mutations are reachable without the management key, and the management port is never exposed by the public Bun.serve. No logic bugs found in any changed path.

No files require special attention — the core logic in config.service.ts, lib/servers/index.ts, and lib/config.ts is consistent and correct.

Important Files Changed

Filename	Overview
apps/backend/src/modules/config/config.service.ts	New file: serialized write queue, rollback-safe atomic persist, full peers/servers CRUD with live connector reconciliation and peer-rekey cascade. Logic is sound and well-commented.
apps/backend/src/modules/config/config.controller.ts	New file: thin controller wrapping ConfigService; canMutate gates mutation route registration; ZodError → BadRequestError funnel in mutate.
apps/backend/src/modules/config/config.router.ts	New file: mutation routes only registered when canMutate; uses hono-openapi zValidator for request-body pre-validation before controller dispatch.
apps/backend/src/middleware/require-management-key.ts	New file: SHA-256 hash of both sides before XOR loop comparison — correct constant-time, length-independent key check.
apps/backend/src/lib/config.ts	Versioned migration system added; migrateConfig uses z.looseObject so downgrade/catch on version only resets the version field — all other config data is preserved. getAppConfig now returns both resolved appConfig and the raw ref-preserving object.
apps/backend/src/lib/servers/index.ts	Replaces static connector arrays with ConnectorManager; live servers/peers/destinations/sources getters filter by enabled; init() is idempotent (pending/initialized guard) so dynamic add is safe.
apps/backend/src/lib/servers/base.ts	Added enabled/disable()/enable() for soft-delete; _initialization eagerly initialized with Promise.withResolvers (non-nullable now); generateId exported; span calls routed through new setSpanAttribute funnel.
apps/backend/src/lib/atomic-write.ts	New file: randomized temp name, permission-preserving chmod, rename(2) atomicity, cleanup on failure — correct design for crash-safe config writes.
apps/backend/src/lib/span-attributes.ts	New file: single funnel for all span attribute writes; redacts sensitive fields, serializes objects, caps at 8 KB; redactUrl masks only sensitive query-param values.
apps/backend/src/index.ts	Wires ConnectorManager, optional ConfigService, and a startManagementServer helper that guards against port collision and ensures the management listener is shut down alongside the public server.
apps/backend/src/management-app.ts	New file: isolated Hono app with secureHeaders + requireManagementKey on *; no public routes share this surface.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Client as API Client
    participant Mgmt as Management Server (MANAGEMENT_PORT)
    participant MW as requireManagementKey
    participant Ctrl as ConfigController
    participant Svc as ConfigService
    participant Q as Serialized Queue
    participant CM as ConnectorManager
    participant FS as config.jsonc

    Client->>Mgmt: PATCH /config/peers/:id X-Management-Key
    Mgmt->>MW: validate key (SHA-256 constant-time)
    MW-->>Mgmt: 401 if invalid
    Mgmt->>Ctrl: updatePeer(id, body)
    Ctrl->>Svc: updatePeer(id, input)
    Note over Svc: PeerConfig.parse resolve secrets / RawPeerConfig preserve refs
    Svc->>Q: enqueue task
    Q->>FS: atomicWrite(newConfig) via tmp rename
    Q->>Svc: "this.raw = next (commit in-memory)"
    Q->>CM: addPeerConnector(resolved) init
    alt URL changed
        Q->>CM: removeConnector(oldId) disable
        Q->>DB: reassignPeerId(oldId, newId)
    end
    Q-->>Svc: resolve
    Svc-->>Ctrl: ok
    Ctrl-->>Client: 200 ok true

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Client as API Client
    participant Mgmt as Management Server (MANAGEMENT_PORT)
    participant MW as requireManagementKey
    participant Ctrl as ConfigController
    participant Svc as ConfigService
    participant Q as Serialized Queue
    participant CM as ConnectorManager
    participant FS as config.jsonc

    Client->>Mgmt: PATCH /config/peers/:id X-Management-Key
    Mgmt->>MW: validate key (SHA-256 constant-time)
    MW-->>Mgmt: 401 if invalid
    Mgmt->>Ctrl: updatePeer(id, body)
    Ctrl->>Svc: updatePeer(id, input)
    Note over Svc: PeerConfig.parse resolve secrets / RawPeerConfig preserve refs
    Svc->>Q: enqueue task
    Q->>FS: atomicWrite(newConfig) via tmp rename
    Q->>Svc: "this.raw = next (commit in-memory)"
    Q->>CM: addPeerConnector(resolved) init
    alt URL changed
        Q->>CM: removeConnector(oldId) disable
        Q->>DB: reassignPeerId(oldId, newId)
    end
    Q-->>Svc: resolve
    Svc-->>Ctrl: ok
    Ctrl-->>Client: 200 ok true

Loading

_{Reviews (4): Last reviewed commit: "fix: seed config service with default co..." | Re-trigger Greptile}

[github-actions]

🐳 Docker image published

This PR has been built and pushed to GHCR:

ghcr.io/roziscoding/jack:pr-24

Pull and run it locally:

docker pull ghcr.io/roziscoding/jack:pr-24
docker run --rm ghcr.io/roziscoding/jack:pr-24

Last built from commit f585c72. Heads up: this image is automatically deleted when the PR is closed.