@volter/twin-fly 0.1.0

package/src/index.ts

@@ -0,0 +1,171 @@
+// @volter/twin-fly — the Fly.io MACHINES API twin (api.machines.dev/v1), built on the shared
+// @volter/world-core kernel. The first REAL-EXECUTION-PLANE compute twin in the catalog: the control
+// plane (apps / machines / volumes / secrets, machine lifecycle states + events, leases, wait)
+// is a faithful, stateful local surface over kernel event-sourced state — and when a machine is
+// created or started the twin ACTUALLY runs `config.image` as a real local Docker container
+// through the injected `FlyContainerRuntime` seam (fly-docker.ts). The supabase doctrine at the
+// compute layer: twin the control plane, run the real engine. Offline by default: the pure-ledger
+// VIRTUAL runtime means every verify, test and gate runs with no Docker daemon anywhere.
+//
+// Bearer auth is faked-but-enforced. No real Fly is ever contacted (the connector's injected
+// executor is the one live boundary, budget-guarded).
+//
+// (Conformance tooling lives in @volter/world-tooling, a dev dependency — not shipped here, and
+// `./fly-conformance.ts` is NOT re-exported: cli.ts imports it lazily.)
+export { handleFlyTwinRequest, flyTwinSnapshot, FLY_API_HOST, FLY_INTERNAL_API_HOST, FLY_RESOURCE_TYPES } from './fly-twin.ts';
+export type { FlyRequest, FlyResponse } from './fly-twin.ts';
+
+export { createFlyTwinFetch, createFlyTwinServer } from './fly-server.ts';
+export type { FlyTwinFetchOptions } from './fly-server.ts';
+export { resolveFlyRuntime } from './fly-runtime-choice.ts';
+export type { FlyServerRuntimeChoice, FlyLocalExecutionOptions } from './fly-runtime-choice.ts';
+
+export {
+  containerSpecOf,
+  FLY_MACHINE_STATES,
+  flyRuntimeEnv,
+  imageRefOf,
+  machinePrivateIp,
+  newInstanceId,
+  newMachineId,
+  newMachineName,
+  newVolumeId,
+  VIRTUAL_FLY_RUNTIME,
+} from './fly-machines.ts';
+export type {
+  FlyContainerRuntime,
+  FlyContainerSpec,
+  FlyExecResult,
+  FlyMachineEvent,
+  FlyMachineState,
+  FlyPortSpec,
+} from './fly-machines.ts';
+
+// NB: `./fly-docker.ts` (the real execution plane) is deliberately NOT re-exported here: the
+// host boundary resolves it lazily (`resolveFlyRuntime('docker')` in fly-runtime-choice.ts, dev plane), so `node:child_process` and the
+// docker CLI wrapper never enter the runtime graph of a consumer that stays virtual. Import it
+// by direct path if you genuinely want the docker runtime in-process.
+
+export {
+  liveFlyExecute,
+  mapApp,
+  mapMachine,
+  mapVolume,
+  pullFlyApps,
+  pullFlyMachines,
+  pullFlyVolumes,
+  syncFlyFromReal,
+  flyExecuteOver,
+  syncFlyFromRemote,
+  performFlyAction,
+} from './fly-connector.ts';
+export type { FlyExecute, LiveFlyOptions } from './fly-connector.ts';
+
+// The client-side rate budget — the fail-closed backstop `liveFlyExecute` routes every live
+// request through. Exported so an operator can inspect spend; there is deliberately no export
+// that disables the guard.
+export {
+  FLY_BUDGET_CEILING,
+  FLY_BUDGET_MAX_RETRY_AFTER_S,
+  FLY_BUDGET_WINDOW_MS,
+  FLY_CALL_WEIGHTS,
+  FLY_RATE_BUDGET,
+  FlyBudget,
+  FlyBudgetError,
+  flyBudgetPath,
+  flyCallWeight,
+} from './fly-budget.ts';
+export type { FlyBudgetErrorKind, FlyBudgetOptions, FlyBudgetReservation, FlyBudgetSnapshot } from './fly-budget.ts';
+
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import { registerPack, referenceField, type TwinPack } from '@volter/world-core';
+import { FLY_RATE_BUDGET as RATE_BUDGET } from './fly-budget.ts';
+import { performFlyAction as perform, syncFlyFromRemote as refresh } from './fly-connector.ts';
+
+export const pack: TwinPack = {
+  vendor: 'fly',
+  // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of the real
+  // state system: perform one entry against Fly, refresh the root from it. Moved 2026-09-08. A performed
+  // machine-create provisions real, billable compute: the head performs only when an operator bound it to
+  // a real state system.
+  protocol: '2',
+  refresh: { every: '5m', onDemand: { atMost: '30s' } }, // the Machines API has no webhooks: polled, or on demand
+  stateSystem: { perform, refresh },
+  // the round trip: an app (its name is Fly's id — the first write may answer 422 name-taken on a branch that
+  // already holds it, and the round trip reads the LAST write's answer), then a volume in it
+  roundTrip: [
+    { method: 'POST', path: '/v1/apps', body: { app_name: 'round-trip', org_slug: 'personal' }, headers: { authorization: 'Bearer round-trip' } },
+    { method: 'POST', path: '/v1/apps/round-trip/volumes', body: { name: 'data', region: 'sjc', size_gb: 1 }, headers: { authorization: 'Bearer round-trip' } },
+  ],
+  // rule 5: a machine, a volume and a secret name their app; a machine's mount names its volume, and a volume
+  // names the machine it is attached to. When the head adopts Fly's id for any of them, the kernel resolves the
+  // referencing side first. The reference trip is a machine in the round trip's app (a mount would bind the one
+  // volume to the first machine — Fly attaches a volume once — so the trip that repeats names only its app).
+  referenceTrip: { method: 'POST', path: '/v1/apps/{{id}}/machines', body: { region: 'sjc', config: { image: 'nginx:1.27' } }, headers: { authorization: 'Bearer round-trip' } },
+  references: [
+    referenceField('machine', 'app_name', 'app'),
+    referenceField('volume', 'app_name', 'app'),
+    referenceField('secret', 'app_name', 'app'),
+    {
+      type: 'machine', to: 'volume',
+      key: (f: Record<string, unknown>) => { const mounts = (f.config as { mounts?: Array<{ volume?: unknown }> } | undefined)?.mounts; const v = mounts?.[0]?.volume; return typeof v === 'string' && v ? v : undefined; },
+      adopt: (f: Record<string, unknown>, vendorId: string) => { const config = (f.config ?? {}) as { mounts?: Array<Record<string, unknown>> }; const mounts = [...(config.mounts ?? [])]; if (mounts[0]) mounts[0] = { ...mounts[0], volume: vendorId }; return { config: { ...config, mounts } }; },
+    },
+    referenceField('volume', 'attached_machine_id', 'machine'),
+  ],
+  parityOrigin: 'http://twin',
+  shapeParity: 'held',
+  // the execution plane: real local Docker containers live outside the world store, by declaration
+  engine: { module: 'fly-docker', note: 'real local Docker containers: a started machine runs config.image; the tree references the container by ref' },
+  // The SAME object fly-budget.ts declares at module load — one source of truth, so registering
+  // the pack and importing the connector can never arm two different ceilings.
+  rateBudget: RATE_BUDGET,
+  transport: 'rest',
+  archetype: 'engine-control',
+  bin: 'world-fly',
+  resources: ['app', 'machine', 'volume', 'secret'],
+  specSource:
+    "Fly.io Machines API — first-party OpenAPI (docs.machines.dev/swagger/doc.json, 'Machines API 1.0') "
+    + 'cross-checked against superfly/fly-go (flyctl\'s own client); fly.io/docs/machines/api for hosts, '
+    + 'response codes and rate limits',
+  description:
+    'Fly.io Machines API twin — apps/machines/volumes/secrets CRUD, the machine lifecycle '
+    + '(states + ledgered events, wait, leases, metadata, exec), connector pull. The execution '
+    + 'plane is REAL local Docker via the injected FlyContainerRuntime seam: created/started '
+    + 'machines genuinely run config.image as local containers (virtual pure-ledger runtime by '
+    + 'default, so everything works offline).',
+  // Adoption + interception, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
+  // 2026-08-31).
+  //
+  // Fly publishes NO first-party npm client (flyctl embeds the Go client superfly/fly-go; the
+  // docs' contract is "point FLY_API_HOSTNAME at the base URL and speak REST"), so the canonical
+  // integration is a hand-written fetch wrapper and the credential env var is the PRIMARY scan
+  // signal: FLY_API_TOKEN — the exact var Fly's own docs export next to FLY_API_HOSTNAME — stems
+  // to `fly` under _API_TOKEN. FLY_API_HOSTNAME itself deliberately does NOT stem: _HOSTNAME is
+  // no credential/endpoint suffix, so it never reaches the lookup. `fly-admin` is the one real
+  // npm client of the modeled surface worth claiming (Supabase's maintained TS client for
+  // api.machines.dev; its base URL is a constructor option, so pointing it at the twin is
+  // configuration). No scope to claim — Fly owns no npm scope for API clients.
+  adoption: {
+    // No official Python SDK - flyctl and `fly-admin` (npm) are the vendor's clients. The community
+    // `fly-python-sdk` is a single-author wrapper with negligible adoption, deliberately unclaimed.
+    pypi: [],
+    sdks: ['fly-admin'], envStems: ['FLY'],
+  },
+  // TWO base hosts, both from Fly's own docs (fly.io/docs/machines/api/working-with-machines-api
+  // "API addresses"):
+  //   • api.machines.dev — the public base URL every out-of-mesh client uses (flyctl's flaps
+  //     transport, fly-admin, plain fetch with FLY_API_HOSTNAME).
+  //   • _api.internal    — the internal base URL (port 4280) reachable only inside a Fly
+  //     WireGuard mesh; claimed so code written for in-mesh deployment redirects to the twin
+  //     instead of failing DNS on a laptop.
+  // fly.io itself (the dashboard/website) and api.fly.io (the legacy GraphQL API this pack does
+  // not model) are deliberately unclaimed: strict egress should fail closed on a surface the twin
+  // does not serve rather than let a half-modeled flow through.
+  hosts: [{ host: 'api.machines.dev' }, { host: '_api.internal' }],
+  // Machines API clients hit https://api.machines.dev/v1/... (or http://_api.internal:4280 from
+  // inside a Fly private network); the dev proxy forwards the /v1/ prefix to the twin.
+  browserRouting: { apiPathPrefix: '/v1/', loaderHost: 'https://api.machines.dev' },
+};
+// registered at import: the kernel learns the pack's state system and its references (protocol 2)
+registerPack(pack);