@fabrika/provider-contract 0.9.0-dev.8 → 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 +3 -3
- package/src/control.ts +100 -8
- package/types/src/control.d.ts +95 -8
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fabrika/provider-contract",
|
|
3
|
-
"version": "0.9.0-dev.
|
|
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.
|
|
46
|
-
"@fabrika/proxy-core": "0.9.0-dev.
|
|
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
|
-
/**
|
|
536
|
-
export interface
|
|
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
|
|
543
|
-
*
|
|
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
|
|
546
|
-
|
|
547
|
-
|
|
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
|
|
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
|
package/types/src/control.d.ts
CHANGED
|
@@ -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
|
-
/**
|
|
462
|
-
export interface
|
|
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
|
|
468
|
-
*
|
|
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
|
|
471
|
-
|
|
472
|
-
|
|
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
|
|
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
|