Class MaintenanceService

constructor

• new MaintenanceService(
      args: {
          kind: ServiceKind | null;
          region: string | null;
          serviceId: string | null;
          valkeyClient: ValkeyClient | null;
      },
  ): MaintenanceService

  Every field is required but nullable rather than optional: the caller has to state each one, and null is the deliberate "not set here" answer. An optional key lets a composition root forget it silently, which is how this service came to read MAINTENANCE_SERVICE_ID off process.env and warn at runtime instead of being handed it.

  Parameters

  • args: {
        kind: ServiceKind | null;
        region: string | null;
        serviceId: string | null;
        valkeyClient: ValkeyClient | null;
    }

    • kind: ServiceKind | null

      null falls back to "api".

    • region: string | null

      null falls back to "unknown", which is what the panel displays.

    • serviceId: string | null

      null only for a process deliberately not individually toggleable: it stays gated by the global flag but never appears in the admin panel.

    • valkeyClient: ValkeyClient | null

  Returns MaintenanceService

Staticinstance

getService

• getService(serviceId: string): Promise<ServiceEntry | null>

  Parameters

  • serviceId: string

  Returns Promise<ServiceEntry | null>

heartbeat

• heartbeat(): void

  Throttled (>=30s), best-effort, non-blocking refresh of this runner.

  Returns void

isActive

• isActive(): Promise<boolean>

  Effective gate state: the global flag OR this service's own flag.

  The global read happens even when serviceId is unset. A process with no MAINTENANCE_SERVICE_ID has no per-service flag to check and no registry entry for an operator to toggle — it is exactly the process the global switch exists for, so it must not short-circuit to false.

  Both reads share one 5s cache window and one round trip.

  A stale cache races the refresh against GATE_MAX_BLOCK_MS rather than awaiting it outright — see that constant for why a gate on the onRequest path must not be allowed to block without a ceiling.

  Returns Promise<boolean>

isGlobalActive

• isGlobalActive(): Promise<boolean>

  Admin read of the global kill-switch. Uncached — operators need truth.

  Returns Promise<boolean>

listInstances

• listInstances(serviceId: string): Promise<InstanceEntry[]>

  Parameters

  • serviceId: string

  Returns Promise<InstanceEntry[]>

listServices

• listServices(): Promise<ServiceEntry[]>

  Returns Promise<ServiceEntry[]>

register

• register(): Promise<void>

  Returns Promise<void>

setGlobal

• setGlobal(
      on: boolean,
  ): Promise<
      | { ok: true; value: { written: boolean } }
      | { error: ReadOnlyError; ok: false },
  >

  written is false when no client or an open breaker skipped the write.

  Parameters

  • on: boolean

  Returns Promise<
      | { ok: true; value: { written: boolean } }
      | { error: ReadOnlyError; ok: false },
  >

setState

• setState(
      serviceId: string,
      on: boolean,
  ): Promise<
      | { error: ReadOnlyError; ok: false }
      | { ok: true; value: { written: boolean } },
  >

  written is false when no client or an open breaker skipped the write.

  Parameters

  • serviceId: string
  • on: boolean

  Returns Promise<
      | { error: ReadOnlyError; ok: false }
      | { ok: true; value: { written: boolean } },
  >