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

Write provisioning intent before a driver creates a device

Cerrado
  • ¿Algo no está bien?
#74 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
25/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
android, ios, typescript
Área
backend, databases, mobile-dev, testing-qa

Línea de trabajo

Comienza con DeviceProvisioner, la llamada driver.provision() y el registro autoritativo de Simlock; después revisa ADR 0021 y las dependencias #72 y #73. Traza el flujo existente de reserva de capacidad y de registro de dispositivos antes de definir las transiciones duraderas de intent para ambas plataformas. Se considera terminado cuando los casos indicados de fallos, reinicios, capacidad, disco, corrupción, limpieza y concurrencia pasan con pruebas de inyección de transiciones.

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

Descripción

task:draft

Part of #70. See ADR 0021.

Purpose

Store provisioning intent before a driver creates or clones a device.

Today, DeviceProvisioner calls driver.provision() before it writes the device record. A crash can leave a device that Simlock cannot identify.

The in-process capacity reservation does not close this crash window.

Proposed record

Add the intent to Simlock's authoritative registry. Do not create a second registry.

type ProvisioningOrigin =
  | {
      kind: "lease-request";
      requesterId: string;
      idempotencyKey: string;
      generation: number;
    }
  | {
      kind: "warm-convergence";
      operationId: string;
      generation: number;
      maintenanceEpoch?: string;
    };

interface ProvisioningIntent {
  id: string;
  version: number;
  origin: ProvisioningOrigin;
  requestedSpec: ManagedShapeRequest;
  resolvedSpec: ResolvedDeviceSpec;
  state:
    | "reserved"
    | "driver-created"
    | "committed"
    | "cleanup-pending"
    | "failed"
    | "quarantined";
  driverDeviceId?: string;
  driverData?: unknown;
  createdAt: number;
  updatedAt: number;
}

An internal owner can expose these transitions:

interface ProvisioningJournal {
  createIntent(input: {
    origin: ProvisioningOrigin;
    requestedSpec: ManagedShapeRequest;
    resolvedSpec: ResolvedDeviceSpec;
  }): Promise<ProvisioningIntent>;
  recordDriverDevice(input: {
    intentId: string;
    expectedVersion: number;
    driverDeviceId: string;
    driverData: unknown;
  }): Promise<ProvisioningIntent>;
  commitDevice(input: {
    intentId: string;
    expectedVersion: number;
  }): Promise<DeviceRecord>;
  failIntent(input: {
    intentId: string;
    expectedVersion: number;
    error: SimlockError;
  }): Promise<void>;
}

The exact record shape can change. The durable origin, pinned resolved shape, fenced transitions, and capacity rules cannot change.

Required sequence

  1. Resolve the shape to one concrete installed device type and runtime.
  2. Check disk space.
  3. Reserve every applicable capacity dimension and store the intent with the resolved shape.
  4. Call the driver with the stable intent ID, pinned resolved shape, and intent-bound ownership provenance.
  5. Store the driver device identity.
  6. Commit the device record and transfer the capacity charge atomically.

Each origin is durable and idempotent. Repeating the same lease generation or warm convergence generation must reuse its intent.

Retries and restart recovery must use the stored resolvedSpec. They must not resolve the request again after the installed catalog changes.

Reserved, driver-created, cleanup-pending, and quarantined intents use every managed and running capacity dimension that their device consumes. Simlock must load these charges before it accepts new lease requests.

Commit must transfer the charge from the intent to the device record without a free-capacity gap or a double charge.

failed is freeable only when Simlock proves that no driver mutation occurred or that cleanup completed. Any possible driver side effect remains capacity-bearing in cleanup-pending or quarantined until ownership-safe cleanup completes.

Disk error

Reuse the Simlock error for insufficient disk space.

interface InsufficientDiskSpaceError {
  code: "INSUFFICIENT_DISK_SPACE";
  requiredBytes?: number;
  availableBytes?: number;
}

Do not call the driver after this error.

Restart recovery

  • Correlate a created device with intent-bound provenance that contains the stable intent ID.
  • Use the device-set or home ownership marker only to authorize access. It is not intent correlation.
  • Continue or roll back an unambiguous intent with its pinned resolved shape.
  • Quarantine an ambiguous record and keep its capacity charged.
  • Fence each durable transition with the expected intent version.
  • Refuse startup when the complete registry document is unreadable.
  • Do not delete a device without both durable intent and valid ownership evidence.

Implement the same record and transitions for iOS and Android.

Completion conditions

  • A crash before the driver call does not create a device.
  • A crash after device creation does not create a duplicate after restart.
  • A crash before registry commit does not leave an unknown device.
  • Startup recovery and a live retry cannot advance the same intent.
  • A stale transition fails without mutation.
  • Lease and warm origins each recover the same intent after restart.
  • A catalog change after intent creation cannot change the device type or runtime used by recovery.
  • No crash transition admits work above an applicable capacity limit.
  • Tests inject a crash at each transition for both platforms.
  • Tests cover corrupt records, a corrupt registry document, low disk, full capacity, uncertain driver failure, and cleanup quarantine.

The lease-request origin depends on #72. The iOS implementation depends on #73.

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

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.