@fabrika/provider-contract 0.9.0-dev.7 → 0.9.0-dev.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fabrika/provider-contract",
3
- "version": "0.9.0-dev.7",
3
+ "version": "0.9.0-dev.9",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",
@@ -42,7 +42,7 @@
42
42
  "test": "bun test"
43
43
  },
44
44
  "dependencies": {
45
- "@fabrika/auth-core": "0.9.0-dev.7",
46
- "@fabrika/proxy-core": "0.9.0-dev.7"
45
+ "@fabrika/auth-core": "0.9.0-dev.9",
46
+ "@fabrika/proxy-core": "0.9.0-dev.9"
47
47
  }
48
48
  }
package/src/control.ts CHANGED
@@ -167,6 +167,17 @@ export interface ProviderDeployInput {
167
167
  readonly applicationObjects?: ApplicationObjects
168
168
  readonly dryRun: boolean
169
169
  readonly sourceBinding?: ProviderSourceBinding
170
+ /**
171
+ * Present on a dev bootstrap: the provider deploys into this workspace's sandbox, which `devSandboxes.ensure` created
172
+ * before the run, and serves it at `origin`. Absent on every other deploy.
173
+ */
174
+ readonly devSandbox?: {
175
+ readonly workspaceId: string
176
+ readonly sandboxId: string
177
+ readonly origin: string
178
+ /** See `ProviderDevSandboxInput.sandboxKey`. */
179
+ readonly sandboxKey: string
180
+ }
170
181
  /** Optional short-lived, run-scoped Operations artifact destination. */
171
182
  readonly artifactUpload?: {
172
183
  readonly url: string
@@ -344,6 +355,24 @@ export interface ProviderNamespaceMember {
344
355
  readonly operationsOrigin?: string
345
356
  /** See `ProviderEnvironment.access`: the proxy table of a contract application comes only from here. */
346
357
  readonly access?: ProviderApprovedAccess
358
+ /**
359
+ * Present for a dev member, which is routed ONLY through these entries (none while it has no sandbox), never through
360
+ * its own `domain` and `access`.
361
+ */
362
+ readonly devSandboxes?: readonly ProviderNamespaceDevSandbox[]
363
+ }
364
+
365
+ /** One workspace sandbox of a `dev` member, which the namespace proxy routes as its own entry. */
366
+ export interface ProviderNamespaceDevSandbox {
367
+ readonly workspaceId: string
368
+ /** The public host the proxy answers the workspace on (`<workspaceId>.<domain>`). */
369
+ readonly host: string
370
+ /** See `ProviderDevSandbox.upstreamHost`. */
371
+ readonly upstreamHost: string
372
+ /** See `ProviderNamespaceMember.proxySecret`: sealed per workspace. */
373
+ readonly proxySecret?: string
374
+ /** The access of the workspace's own published bootstrap run. */
375
+ readonly access: ProviderApprovedAccess
347
376
  }
348
377
 
349
378
  /** One idempotent namespace lifecycle invocation. */
@@ -356,6 +385,11 @@ export interface ProviderNamespaceMutationInput {
356
385
  * mutation; absent or null shows the fabrika mark. A provider passes it only to a proxy that can parse it.
357
386
  */
358
387
  readonly brand?: InstallationBrand | null
388
+ /**
389
+ * Present when a member is a `dev` environment: the namespace's sandbox host is provisioned with it as its API key, and
390
+ * see `ProviderDevSandboxInput.sandboxKey`. Absent, the provider provisions no sandbox host.
391
+ */
392
+ readonly sandboxKey?: string
359
393
  readonly signal: AbortSignal
360
394
  readonly events: ProviderNamespaceEvents
361
395
  }
@@ -384,6 +418,18 @@ export const PROVIDER_NAMESPACE_IMMUTABLE = 'namespaceImmutable'
384
418
  */
385
419
  export const PROVIDER_NAMESPACE_UPDATE_UNCONFIRMED = 'namespaceUpdateUnconfirmed'
386
420
 
421
+ /**
422
+ * The `code` of a `ProviderNamespaceError` a `devSandboxes` call throws when the namespace's sandbox host has no room
423
+ * to create or wake one more sandbox. Nothing changed; it succeeds once another sandbox is parked or removed.
424
+ */
425
+ export const PROVIDER_DEV_CAPACITY = 'devCapacity'
426
+
427
+ /**
428
+ * The `code` of a `ProviderNamespaceError` a `devSandboxes` call throws when the namespace has no sandbox host yet.
429
+ * Nothing changed; it succeeds once a namespace mutation handed the sandbox host key has created the host.
430
+ */
431
+ export const PROVIDER_DEV_HOST_PENDING = 'devHostPending'
432
+
387
433
  /** One provider-described change, safe to audit: names and values only, never a credential. */
388
434
  export interface ProviderNamespaceChange {
389
435
  readonly field: string
@@ -532,19 +578,65 @@ export interface ProviderAuthoring {
532
578
  readonly protectedFiles: readonly string[]
533
579
  }
534
580
 
535
- /** One call on the service of a `dev` environment, between its bootstrap runs. */
536
- export interface ProviderDevEnvironmentInput {
581
+ /** The provider's handle on one workspace sandbox, which Control persists; stable for the workspace's life. */
582
+ export interface ProviderDevSandboxRef {
583
+ readonly sandboxId: string
584
+ }
585
+
586
+ /** One running workspace sandbox of a `dev` environment. */
587
+ export interface ProviderDevSandbox {
588
+ readonly sandboxId: string
589
+ /** The base image the sandbox was created from. */
590
+ readonly baseDigest: string
591
+ /** The Host the namespace proxy sends to reach the sandbox's application port (e.g. `3000-<id>.<box domain>`). */
592
+ readonly upstreamHost: string
593
+ }
594
+
595
+ /** Create a workspace's sandbox, or return the one it already has. */
596
+ export interface ProviderDevSandboxEnsureInput {
537
597
  readonly environment: ProviderEnvironment
598
+ readonly workspaceId: string
599
+ /** See `ProviderDevSandboxInput.sandboxKey`. */
600
+ readonly sandboxKey: string
601
+ readonly signal: AbortSignal
602
+ }
603
+
604
+ /** One lifecycle call on an existing workspace sandbox. */
605
+ export interface ProviderDevSandboxInput {
606
+ readonly environment: ProviderEnvironment
607
+ readonly sandbox: ProviderDevSandboxRef
608
+ /** The bearer of the namespace's sandbox host API, composed by Control from its vault for this call; never persisted or logged. */
609
+ readonly sandboxKey: string
610
+ readonly signal: AbortSignal
611
+ }
612
+
613
+ /** Remove a workspace's sandbox; with no recorded `sandbox`, the one an unrecorded `ensure` may have created. */
614
+ export interface ProviderDevSandboxRemoveInput {
615
+ readonly environment: ProviderEnvironment
616
+ readonly workspaceId: string
617
+ readonly sandbox: ProviderDevSandboxRef | null
618
+ /** See `ProviderDevSandboxInput.sandboxKey`. */
619
+ readonly sandboxKey: string
538
620
  readonly signal: AbortSignal
539
621
  }
540
622
 
541
623
  /**
542
- * The service of a `dev` environment outside a run (ADR-0049): Control stops it after an idle period and starts it on
543
- * the next commit. Files the launcher wrote survive both.
624
+ * The per-workspace sandboxes of a `dev` environment outside a run. Every call is idempotent: `ensure` creates at most
625
+ * one sandbox per `workspaceId` and returns it running, `park` and `wake` converge on their state, and `remove` treats a
626
+ * sandbox already gone as removed. A full sandbox host throws `PROVIDER_DEV_CAPACITY`, a namespace without one yet
627
+ * `PROVIDER_DEV_HOST_PENDING`; `remove` there is a no-op, since no sandbox can exist.
544
628
  */
545
- export interface ProviderDevEnvironments {
546
- stop(input: ProviderDevEnvironmentInput): Promise<void>
547
- start(input: ProviderDevEnvironmentInput): Promise<void>
629
+ export interface ProviderDevSandboxes {
630
+ /**
631
+ * Mutation-free check that the environment's placement can serve a workspace sandbox. Control calls it before it
632
+ * records one, because a recorded sandbox reaches every later republish of the namespace. A refusal is a
633
+ * `ProviderNamespaceError` that is not retryable, whose one-line message the author may read; any other throw is a failure.
634
+ */
635
+ admit(input: { readonly environment: ProviderEnvironment }): void
636
+ ensure(input: ProviderDevSandboxEnsureInput): Promise<ProviderDevSandbox>
637
+ park(input: ProviderDevSandboxInput): Promise<void>
638
+ wake(input: ProviderDevSandboxInput): Promise<void>
639
+ remove(input: ProviderDevSandboxRemoveInput): Promise<void>
548
640
  }
549
641
 
550
642
  /**
@@ -577,7 +669,7 @@ export interface ControlProvider {
577
669
  */
578
670
  readonly applicationHopSecret?: true
579
671
  /** Absent means the provider runs no `dev` environment, and Control refuses one. */
580
- readonly devEnvironments?: ProviderDevEnvironments
672
+ readonly devSandboxes?: ProviderDevSandboxes
581
673
  /**
582
674
  * Whether an environment at this approved access is served the ops channel through which Control reaches its object
583
675
  * (ADR-0069), so its deploy gets `FABRIKA_OPS_KEY_DIGESTS`. The release gate is the provider's, so core keeps no
@@ -151,6 +151,17 @@ export interface ProviderDeployInput {
151
151
  readonly applicationObjects?: ApplicationObjects;
152
152
  readonly dryRun: boolean;
153
153
  readonly sourceBinding?: ProviderSourceBinding;
154
+ /**
155
+ * Present on a dev bootstrap: the provider deploys into this workspace's sandbox, which `devSandboxes.ensure` created
156
+ * before the run, and serves it at `origin`. Absent on every other deploy.
157
+ */
158
+ readonly devSandbox?: {
159
+ readonly workspaceId: string;
160
+ readonly sandboxId: string;
161
+ readonly origin: string;
162
+ /** See `ProviderDevSandboxInput.sandboxKey`. */
163
+ readonly sandboxKey: string;
164
+ };
154
165
  /** Optional short-lived, run-scoped Operations artifact destination. */
155
166
  readonly artifactUpload?: {
156
167
  readonly url: string;
@@ -292,6 +303,23 @@ export interface ProviderNamespaceMember {
292
303
  readonly operationsOrigin?: string;
293
304
  /** See `ProviderEnvironment.access`: the proxy table of a contract application comes only from here. */
294
305
  readonly access?: ProviderApprovedAccess;
306
+ /**
307
+ * Present for a dev member, which is routed ONLY through these entries (none while it has no sandbox), never through
308
+ * its own `domain` and `access`.
309
+ */
310
+ readonly devSandboxes?: readonly ProviderNamespaceDevSandbox[];
311
+ }
312
+ /** One workspace sandbox of a `dev` member, which the namespace proxy routes as its own entry. */
313
+ export interface ProviderNamespaceDevSandbox {
314
+ readonly workspaceId: string;
315
+ /** The public host the proxy answers the workspace on (`<workspaceId>.<domain>`). */
316
+ readonly host: string;
317
+ /** See `ProviderDevSandbox.upstreamHost`. */
318
+ readonly upstreamHost: string;
319
+ /** See `ProviderNamespaceMember.proxySecret`: sealed per workspace. */
320
+ readonly proxySecret?: string;
321
+ /** The access of the workspace's own published bootstrap run. */
322
+ readonly access: ProviderApprovedAccess;
295
323
  }
296
324
  /** One idempotent namespace lifecycle invocation. */
297
325
  export interface ProviderNamespaceMutationInput {
@@ -303,6 +331,11 @@ export interface ProviderNamespaceMutationInput {
303
331
  * mutation; absent or null shows the fabrika mark. A provider passes it only to a proxy that can parse it.
304
332
  */
305
333
  readonly brand?: InstallationBrand | null;
334
+ /**
335
+ * Present when a member is a `dev` environment: the namespace's sandbox host is provisioned with it as its API key, and
336
+ * see `ProviderDevSandboxInput.sandboxKey`. Absent, the provider provisions no sandbox host.
337
+ */
338
+ readonly sandboxKey?: string;
306
339
  readonly signal: AbortSignal;
307
340
  readonly events: ProviderNamespaceEvents;
308
341
  }
@@ -326,6 +359,16 @@ export declare const PROVIDER_NAMESPACE_IMMUTABLE = "namespaceImmutable";
326
359
  * and is not confirmed. Any other failure means nothing changed. Applying the same plan again must converge.
327
360
  */
328
361
  export declare const PROVIDER_NAMESPACE_UPDATE_UNCONFIRMED = "namespaceUpdateUnconfirmed";
362
+ /**
363
+ * The `code` of a `ProviderNamespaceError` a `devSandboxes` call throws when the namespace's sandbox host has no room
364
+ * to create or wake one more sandbox. Nothing changed; it succeeds once another sandbox is parked or removed.
365
+ */
366
+ export declare const PROVIDER_DEV_CAPACITY = "devCapacity";
367
+ /**
368
+ * The `code` of a `ProviderNamespaceError` a `devSandboxes` call throws when the namespace has no sandbox host yet.
369
+ * Nothing changed; it succeeds once a namespace mutation handed the sandbox host key has created the host.
370
+ */
371
+ export declare const PROVIDER_DEV_HOST_PENDING = "devHostPending";
329
372
  /** One provider-described change, safe to audit: names and values only, never a credential. */
330
373
  export interface ProviderNamespaceChange {
331
374
  readonly field: string;
@@ -458,18 +501,62 @@ export interface ProviderAuthoring {
458
501
  /** The file NAMES (no `/`) that configure the provider's deploy; a workspace changes none of them, at any depth. */
459
502
  readonly protectedFiles: readonly string[];
460
503
  }
461
- /** One call on the service of a `dev` environment, between its bootstrap runs. */
462
- export interface ProviderDevEnvironmentInput {
504
+ /** The provider's handle on one workspace sandbox, which Control persists; stable for the workspace's life. */
505
+ export interface ProviderDevSandboxRef {
506
+ readonly sandboxId: string;
507
+ }
508
+ /** One running workspace sandbox of a `dev` environment. */
509
+ export interface ProviderDevSandbox {
510
+ readonly sandboxId: string;
511
+ /** The base image the sandbox was created from. */
512
+ readonly baseDigest: string;
513
+ /** The Host the namespace proxy sends to reach the sandbox's application port (e.g. `3000-<id>.<box domain>`). */
514
+ readonly upstreamHost: string;
515
+ }
516
+ /** Create a workspace's sandbox, or return the one it already has. */
517
+ export interface ProviderDevSandboxEnsureInput {
463
518
  readonly environment: ProviderEnvironment;
519
+ readonly workspaceId: string;
520
+ /** See `ProviderDevSandboxInput.sandboxKey`. */
521
+ readonly sandboxKey: string;
522
+ readonly signal: AbortSignal;
523
+ }
524
+ /** One lifecycle call on an existing workspace sandbox. */
525
+ export interface ProviderDevSandboxInput {
526
+ readonly environment: ProviderEnvironment;
527
+ readonly sandbox: ProviderDevSandboxRef;
528
+ /** The bearer of the namespace's sandbox host API, composed by Control from its vault for this call; never persisted or logged. */
529
+ readonly sandboxKey: string;
530
+ readonly signal: AbortSignal;
531
+ }
532
+ /** Remove a workspace's sandbox; with no recorded `sandbox`, the one an unrecorded `ensure` may have created. */
533
+ export interface ProviderDevSandboxRemoveInput {
534
+ readonly environment: ProviderEnvironment;
535
+ readonly workspaceId: string;
536
+ readonly sandbox: ProviderDevSandboxRef | null;
537
+ /** See `ProviderDevSandboxInput.sandboxKey`. */
538
+ readonly sandboxKey: string;
464
539
  readonly signal: AbortSignal;
465
540
  }
466
541
  /**
467
- * The service of a `dev` environment outside a run (ADR-0049): Control stops it after an idle period and starts it on
468
- * the next commit. Files the launcher wrote survive both.
542
+ * The per-workspace sandboxes of a `dev` environment outside a run. Every call is idempotent: `ensure` creates at most
543
+ * one sandbox per `workspaceId` and returns it running, `park` and `wake` converge on their state, and `remove` treats a
544
+ * sandbox already gone as removed. A full sandbox host throws `PROVIDER_DEV_CAPACITY`, a namespace without one yet
545
+ * `PROVIDER_DEV_HOST_PENDING`; `remove` there is a no-op, since no sandbox can exist.
469
546
  */
470
- export interface ProviderDevEnvironments {
471
- stop(input: ProviderDevEnvironmentInput): Promise<void>;
472
- start(input: ProviderDevEnvironmentInput): Promise<void>;
547
+ export interface ProviderDevSandboxes {
548
+ /**
549
+ * Mutation-free check that the environment's placement can serve a workspace sandbox. Control calls it before it
550
+ * records one, because a recorded sandbox reaches every later republish of the namespace. A refusal is a
551
+ * `ProviderNamespaceError` that is not retryable, whose one-line message the author may read; any other throw is a failure.
552
+ */
553
+ admit(input: {
554
+ readonly environment: ProviderEnvironment;
555
+ }): void;
556
+ ensure(input: ProviderDevSandboxEnsureInput): Promise<ProviderDevSandbox>;
557
+ park(input: ProviderDevSandboxInput): Promise<void>;
558
+ wake(input: ProviderDevSandboxInput): Promise<void>;
559
+ remove(input: ProviderDevSandboxRemoveInput): Promise<void>;
473
560
  }
474
561
  /**
475
562
  * The control-plane capability bundle selected statically by one composition root.
@@ -504,7 +591,7 @@ export interface ControlProvider {
504
591
  */
505
592
  readonly applicationHopSecret?: true;
506
593
  /** Absent means the provider runs no `dev` environment, and Control refuses one. */
507
- readonly devEnvironments?: ProviderDevEnvironments;
594
+ readonly devSandboxes?: ProviderDevSandboxes;
508
595
  /**
509
596
  * Whether an environment at this approved access is served the ops channel through which Control reaches its object
510
597
  * (ADR-0069), so its deploy gets `FABRIKA_OPS_KEY_DIGESTS`. The release gate is the provider's, so core keeps no