Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Add durable maintenance prepare and resume operations

Cerrado
  • ¿Algo no está bien?
#77 1 comentario 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
35/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
typescript
Área
api, backend, distributed-systems

Línea de trabajo

Comienza con ADR 0021 y la API del cliente en este issue, y luego rastrea las dependencias #71, #72, #73, #74 y #76. Define las transiciones de estado duraderas de prepare/resume y verifica cada condición de finalización indicada, incluido el comportamiento tras un reinicio, la idempotencia de epoch, la espera del external-fence y la reapertura de la admisión solo después de la convergencia en caliente.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

task:draft

Part of #70. See ADR 0021.

Purpose

Add a durable maintenance mode that stays active after a process restart.

The current reset flow uses an in-memory fence. It releases leases, resets devices, and then reopens admission.

Host needs one prepare operation and one resume operation. Host must not call Simlock's internal cleanup steps.

Client API

type MaintenanceState =
  | "preparing"
  | "drained"
  | "resuming"
  | "awaiting-external-fence"
  | "ready"
  | "failed";

interface MaintenanceStatus {
  epoch: string;
  state: MaintenanceState;
  activeLeaseCount: number;
  activeMutationCount: number;
  activation?: {
    deviceId: string;
    generation: number;
  };
  error?: SimlockError;
}

interface SimlockAdminClient {
  prepareMaintenance(input: { epoch: string }): Promise<MaintenanceStatus>;
  getMaintenanceStatus(input: { epoch: string }): Promise<MaintenanceStatus>;
  confirmMaintenanceActivation(input: {
    epoch: string;
    deviceId: string;
    generation: number;
  }): Promise<MaintenanceStatus>;
  resumeMaintenance(input: { epoch: string }): Promise<MaintenanceStatus>;
}

Prepare operation

prepareMaintenance must do these steps:

  1. Store the epoch and close lease and background-lifecycle admission in one serialized durable transition.
  2. Stop every background lifecycle producer.
  3. Release all leases.
  4. Wait for lifecycle mutations to finish.
  5. Reconcile only owned devices.
  6. Return drained with both active counts at zero.

Read-only catalog and status operations can stay available.

Resume operation

resumeMaintenance is a durable loop:

  1. Load the stored epoch.
  2. Complete startup reconciliation.
  3. Advance the configured warm target from #76 through its single core convergence owner.
  4. If a reusable identity needs an execution fence, persist and return awaiting-external-fence with its device ID and generation. Keep Simlock drained.
  5. Use the active epoch to confirm the same core activation transition that #76 defines.
  6. After idempotent confirmation, repeat resumeMaintenance for the same epoch and continue convergence.
  7. Return ready and reopen lease admission only after warm convergence settles.

Epoch rules

  • Repeating an operation for the same epoch returns the same progress or result.
  • A different epoch returns MAINTENANCE_EPOCH_ACTIVE without a mutation.
  • A stale resume or activation message cannot change a newer epoch or generation.
  • A non-epoch warm mutation cannot advance an identity while the epoch is active.
  • A client disconnect stops only that client's wait.
  • A daemon restart keeps the epoch active and lease admission closed.
  • The epoch has no TTL. Failure or supervisor death keeps Simlock drained.
  • Simlock can clear the active epoch only after resumeMaintenance returns ready.
  • Keep the terminal result for a configured recovery period so a lost response can be replayed.

Scope

Host owns session shutdown, artifact cleanup, and process restart order. Simlock owns allocator drain and device recovery.

The Host front-end must not expose these methods. Only the local managed adapter can call them through the Host admin boundary and the authenticated admin client from #71.

The adapter can call prepareMaintenance only while it holds an unforgeable in-process capability. Host creates this capability after it fences and drains device mutations, completes canonical session teardown, releases mapped Simlock leases, and proves zero live runner. Simlock receives only the epoch.

Completion conditions

  • Prepare cannot admit a lease or background mutation after it stores the epoch.
  • Prepare cannot return drained while a lease or lifecycle mutation exists.
  • Background refill, health recovery, quarantine retry, and the cleanup reaper cannot start work after the fence.
  • Restart during maintenance does not reopen lease admission.
  • Repeated prepare and resume calls do not repeat destructive work.
  • Cleanup cannot target a leased, foreign, or unverified device.
  • Resume stays drained while an external fence is pending.
  • Non-epoch convergence and activation fail without mutation while maintenance is active.
  • Resume reopens admission only after reconciliation, warm convergence, and required fence confirmation.

Depends on #71, #73, and #74. Reusable-identity activation also depends on #72. Warm convergence depends on #76.

Lenguaje dominante
TypeScript
Estrellas
19
Forks
1
Merge medio
6 h 36 min
PR fusionados (30 d)
170

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de callstackincubator/simlock

Todos los issues de callstackincubator/simlock

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.