@fungi.computer/oyster 0.32.0 → 0.33.0
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/README.md +59 -0
- package/dist/app-test-copies.d.ts +87 -0
- package/dist/app-test-copies.js +170 -0
- package/dist/app-test-copy-page.d.ts +4 -0
- package/dist/app-test-copy-page.js +89 -0
- package/dist/browser/operations.d.ts +1 -1
- package/dist/cloudflare.d.ts +68 -3
- package/dist/cloudflare.js +214 -3
- package/dist/embed-metafiles.js +2 -2
- package/dist/host.d.ts +16 -0
- package/dist/host.js +309 -1
- package/dist/installation-operations.d.ts +247 -8
- package/dist/installation-operations.js +145 -7
- package/dist/installation-recovery-page.d.ts +24 -0
- package/dist/installation-recovery-page.js +168 -0
- package/dist/older-oyster-store.d.ts +1 -1
- package/dist/older-oyster-store.js +2 -4
- package/dist/page/mount.d.ts +2 -101
- package/dist/page/mount.js +1 -22
- package/dist/page-config.d.ts +102 -0
- package/dist/page-config.js +24 -0
- package/dist/page-script.js +1 -1
- package/dist/recovery-style.d.ts +5 -0
- package/dist/recovery-style.js +32 -0
- package/dist/standalone/agents.d.ts +1 -1
- package/dist/upgrade/old-worker-http.d.ts +2 -0
- package/dist/upgrade/old-worker-http.js +22 -0
- package/dist/upgrade/old-worker-readonly.d.ts +14 -0
- package/dist/upgrade/old-worker-readonly.js +22 -0
- package/dist/upgrade/old-worker-sql.d.ts +10 -0
- package/dist/upgrade/old-worker-sql.js +68 -0
- package/dist/upgrade/old-worker-stream.d.ts +12 -0
- package/dist/upgrade/old-worker-stream.js +54 -0
- package/dist/upgrade/private-stage.d.ts +23 -0
- package/dist/upgrade/private-stage.js +109 -0
- package/dist/upgrade/standalone-001.d.ts +16 -0
- package/dist/upgrade/standalone-001.js +31 -0
- package/dist/upgrade/standalone-01.d.ts +37 -0
- package/dist/upgrade/standalone-01.js +55 -0
- package/dist/upgrade/standalone-02.d.ts +37 -0
- package/dist/upgrade/standalone-02.js +55 -0
- package/dist/workers.d.ts +15 -1
- package/dist/workers.js +117 -7
- package/docs/api/README.md +8 -3
- package/docs/api/cloudflare.md +57 -0
- package/docs/api/host.md +223 -14
- package/docs/api/page/mount.md +10 -78
- package/docs/api/workers-git.md +246 -1
- package/docs/api/workers.md +352 -14
- package/package.json +23 -10
package/dist/workers.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { ApprovalListInput, ApprovalAnswerInput, AutoApproveInput } from "@fungi.computer/approvals";
|
|
2
|
-
import type { HostActor } from "@fungi.computer/puffball/app";
|
|
2
|
+
import type { HostActor, AppMethodCallContext } from "@fungi.computer/puffball/app";
|
|
3
3
|
import { type OysterApprovalCall } from "./approval-home.js";
|
|
4
4
|
import { type BootCapabilityGrant, type BootCapabilityLease } from "./boot-capability.js";
|
|
5
5
|
import { type Installation } from "./apps/installation.js";
|
|
@@ -22,6 +22,7 @@ import * as Schema from "effect/Schema";
|
|
|
22
22
|
import type { Release } from "@fungi.computer/puffball";
|
|
23
23
|
import { type Backend, type Instance, type OwnerState } from "./index.js";
|
|
24
24
|
import { r2ArtifactStore, type FrameBindingReply, type FrameBindingMethod, type FrameBindingProps } from "./cloudflare.js";
|
|
25
|
+
import type { AppTestCopy, AppTestCopyAuthority } from "./app-test-copies.js";
|
|
25
26
|
import { type BackgroundFrameState, type InvocationFacts, type InvocationFrame } from "./invocation.js";
|
|
26
27
|
import { type InstallationCommit, type InstanceResult, type OysterAuth, type OysterHost, type OysterJson } from "./host.js";
|
|
27
28
|
import { type AppStorageResult, type AppStorageWrite, type AppStorageReset, type ResolvedAppStorage } from "@fungi.computer/agar/storage";
|
|
@@ -377,10 +378,23 @@ export declare class OysterInstance<Env extends OysterWorkerEnv = OysterWorkerEn
|
|
|
377
378
|
private runtime;
|
|
378
379
|
private limits;
|
|
379
380
|
private readonly frames;
|
|
381
|
+
private readonly testCopies;
|
|
380
382
|
/** Content-addressed backends are verified once per Instance, not per call. */
|
|
381
383
|
private readonly backends;
|
|
382
384
|
private readonly gitJournal;
|
|
383
385
|
constructor(ctx: DurableObjectState, env: Env);
|
|
386
|
+
/** Every wake owner shares the native alarm; none may postpone another. */
|
|
387
|
+
private scheduleWake;
|
|
388
|
+
/** Open only under the existing Instance serialization and pinned tenant. */
|
|
389
|
+
openTestCopy(authority: AppTestCopyAuthority, requestId: string, tenantId?: TenantId): Promise<InstanceResult<AppTestCopy>>;
|
|
390
|
+
/** Observation rechecks both applied selection and current registry incarnation. */
|
|
391
|
+
inspectTestCopy(authority: AppTestCopyAuthority, tenantId?: TenantId): Promise<InstanceResult<AppTestCopy | null>>;
|
|
392
|
+
/** A delayed discard cannot target a later sibling. */
|
|
393
|
+
discardTestCopy(authority: AppTestCopyAuthority, copyId: string, tenantId?: TenantId): Promise<InstanceResult<boolean>>;
|
|
394
|
+
/** Uses the ordinary invocation facade, without live bindings or host context. */
|
|
395
|
+
testCopyBackend(authority: AppTestCopyAuthority, copyId: string, request: Request, limits?: GuestLimits, tenantId?: TenantId): Promise<Response>;
|
|
396
|
+
/** Declared methods share copy isolation, never a live invocation frame or binding env. */
|
|
397
|
+
callTestCopy(authority: AppTestCopyAuthority, copyId: string, name: string, input: Schema.Json, caller: AppMethodCallContext, limits?: GuestLimits, tenantId?: TenantId): Promise<InstanceResult<unknown>>;
|
|
384
398
|
/** The deployable root's host for one pinned tenant; this plain root is the single owner key. */
|
|
385
399
|
protected hostFor(scope: TenantScope): Promise<OysterHost>;
|
|
386
400
|
/** Reconstruct current host admission for each wake; non-default tenants get no wakes. */
|
package/dist/workers.js
CHANGED
|
@@ -36,7 +36,7 @@ import * as Schema from "effect/Schema";
|
|
|
36
36
|
import * as Stream from "effect/Stream";
|
|
37
37
|
import { releaseSchema } from "@fungi.computer/puffball/effect";
|
|
38
38
|
import { AppInstanceError, } from "./index.js";
|
|
39
|
-
import { createCloudflareAppInstance, r2ArtifactStore, createCloudflareInvocationGate, edgeVerifiedObjectCache, decodeFrameBindingProps, captureFrameBindingReply, frameBindingEntrypoint, backgroundFrameMethods, } from "./cloudflare.js";
|
|
39
|
+
import { createCloudflareAppInstance, createCloudflareAppTestCopies, r2ArtifactStore, createCloudflareInvocationGate, edgeVerifiedObjectCache, decodeFrameBindingProps, captureFrameBindingReply, frameBindingEntrypoint, backgroundFrameMethods, } from "./cloudflare.js";
|
|
40
40
|
import { invocationFactsSchema, assertBackgroundBinding, admitBackgroundFrame, } from "./invocation.js";
|
|
41
41
|
import { deliverBackground, deliverGitPush } from "./internal/delivery.js";
|
|
42
42
|
import { reportSlowInvocation } from "./internal/invocation-timing.js";
|
|
@@ -568,6 +568,18 @@ export class OysterBinding extends oysterBindingEntrypoint(oysterBindings) {
|
|
|
568
568
|
function instanceHandle(target, scope, budget) {
|
|
569
569
|
const { tenantId, origin } = scope;
|
|
570
570
|
return {
|
|
571
|
+
testCopies: {
|
|
572
|
+
open: (authority, requestId) => target.openTestCopy(authority, requestId, tenantId),
|
|
573
|
+
inspect: (authority) => target.inspectTestCopy(authority, tenantId),
|
|
574
|
+
discard: (authority, copyId) => target.discardTestCopy(authority, copyId, tenantId),
|
|
575
|
+
fetch: (authority, copyId, request) => target.testCopyBackend(authority, copyId, request, budget, tenantId),
|
|
576
|
+
call: async (authority, copyId, name, input, caller) => {
|
|
577
|
+
const reply = await target.callTestCopy(authority, copyId, name, input, caller, budget, tenantId);
|
|
578
|
+
return reply.ok
|
|
579
|
+
? { ok: true, value: appMethodReplySchema.parse(reply.value) }
|
|
580
|
+
: reply;
|
|
581
|
+
},
|
|
582
|
+
},
|
|
571
583
|
prepare: (state, release) => target.prepare(state, release, budget, { tenantId, origin }),
|
|
572
584
|
apply: (state, release) => target.apply(state, release, budget, { tenantId, origin }),
|
|
573
585
|
fetch: (facts, request) => target.backend(facts, request, budget, tenantId),
|
|
@@ -600,6 +612,7 @@ export class OysterInstance extends DurableObject {
|
|
|
600
612
|
runtime;
|
|
601
613
|
limits = guestLimits();
|
|
602
614
|
frames;
|
|
615
|
+
testCopies;
|
|
603
616
|
/** Content-addressed backends are verified once per Instance, not per call. */
|
|
604
617
|
backends;
|
|
605
618
|
gitJournal;
|
|
@@ -616,6 +629,44 @@ export class OysterInstance extends DurableObject {
|
|
|
616
629
|
this.backends = backendCache(r2ArtifactStore(env.RELEASES));
|
|
617
630
|
this.runtime = this.createRuntime(this.limits);
|
|
618
631
|
this.frames = createCloudflareInvocationGate(ctx, (frame) => this.closeBackground(frame));
|
|
632
|
+
this.testCopies = createCloudflareAppTestCopies(ctx, env.LOADER, {
|
|
633
|
+
limits: () => this.limits,
|
|
634
|
+
source: () => Effect.tryPromise({
|
|
635
|
+
try: async () => {
|
|
636
|
+
const instance = await Effect.runPromise(this.runtime.inspect());
|
|
637
|
+
if (instance?.owner.id !== this.installationId())
|
|
638
|
+
return null;
|
|
639
|
+
const store = registryInstallations(env, this.scope());
|
|
640
|
+
const installation = await store.get(instance.owner.id);
|
|
641
|
+
if (!isCommittedInstallation(installation, { ...instance, status: "enabled" }, this.release(instance.releaseId)))
|
|
642
|
+
return null;
|
|
643
|
+
return { instance, storeGeneration: await store.generation() };
|
|
644
|
+
},
|
|
645
|
+
catch: (cause) => cause instanceof Error
|
|
646
|
+
? cause
|
|
647
|
+
: new Error("Copy source unavailable"),
|
|
648
|
+
}),
|
|
649
|
+
resolve: (releaseId) => Effect.tryPromise({
|
|
650
|
+
try: async () => {
|
|
651
|
+
const release = this.release(releaseId);
|
|
652
|
+
const backend = await this.backends(release);
|
|
653
|
+
if (backend === null)
|
|
654
|
+
throw new Error("Release has no backend");
|
|
655
|
+
return {
|
|
656
|
+
release,
|
|
657
|
+
...backend,
|
|
658
|
+
api: backend.declaration?.api ?? null,
|
|
659
|
+
};
|
|
660
|
+
},
|
|
661
|
+
catch: (cause) => cause instanceof Error
|
|
662
|
+
? cause
|
|
663
|
+
: new Error("Copy Release unavailable"),
|
|
664
|
+
}),
|
|
665
|
+
wake: (at) => Effect.tryPromise({
|
|
666
|
+
try: () => this.scheduleWake(at),
|
|
667
|
+
catch: (cause) => cause instanceof Error ? cause : new Error("Copy wake unavailable"),
|
|
668
|
+
}),
|
|
669
|
+
});
|
|
619
670
|
// Local delivery avoids calling this Instance's own RPC stub from its alarm.
|
|
620
671
|
const instances = {
|
|
621
672
|
get: (instanceId) => this.localInstance(instanceId),
|
|
@@ -648,13 +699,53 @@ export class OysterInstance extends DurableObject {
|
|
|
648
699
|
receipt: { lane: wake.lane, epoch: wake.epoch },
|
|
649
700
|
};
|
|
650
701
|
},
|
|
651
|
-
scheduleWake: (at) =>
|
|
652
|
-
const current = await transaction.getAlarm();
|
|
653
|
-
if (current === null || at < current)
|
|
654
|
-
await transaction.setAlarm(at);
|
|
655
|
-
}),
|
|
702
|
+
scheduleWake: (at) => this.scheduleWake(at),
|
|
656
703
|
}));
|
|
657
704
|
}
|
|
705
|
+
/** Every wake owner shares the native alarm; none may postpone another. */
|
|
706
|
+
scheduleWake(at) {
|
|
707
|
+
return this.ctx.storage.transaction(async (transaction) => {
|
|
708
|
+
const current = await transaction.getAlarm();
|
|
709
|
+
if (current === null || at < current)
|
|
710
|
+
await transaction.setAlarm(at);
|
|
711
|
+
});
|
|
712
|
+
}
|
|
713
|
+
/** Open only under the existing Instance serialization and pinned tenant. */
|
|
714
|
+
openTestCopy(authority, requestId, tenantId = defaultTenant) {
|
|
715
|
+
this.requireTenant(tenantId);
|
|
716
|
+
return this.frames.exclusive(() => result(this.testCopies.open(authority, requestId)));
|
|
717
|
+
}
|
|
718
|
+
/** Observation rechecks both applied selection and current registry incarnation. */
|
|
719
|
+
inspectTestCopy(authority, tenantId = defaultTenant) {
|
|
720
|
+
this.requireTenant(tenantId);
|
|
721
|
+
return this.frames.exclusive(() => result(this.testCopies.inspect(authority)));
|
|
722
|
+
}
|
|
723
|
+
/** A delayed discard cannot target a later sibling. */
|
|
724
|
+
discardTestCopy(authority, copyId, tenantId = defaultTenant) {
|
|
725
|
+
this.requireTenant(tenantId);
|
|
726
|
+
return this.frames.exclusive(() => result(this.testCopies.discard(authority, copyId)));
|
|
727
|
+
}
|
|
728
|
+
/** Uses the ordinary invocation facade, without live bindings or host context. */
|
|
729
|
+
async testCopyBackend(authority, copyId, request, limits, tenantId = defaultTenant) {
|
|
730
|
+
this.requireTenant(tenantId);
|
|
731
|
+
try {
|
|
732
|
+
return await this.frames.exclusive(() => {
|
|
733
|
+
this.runtimeFor(limits);
|
|
734
|
+
return Effect.runPromise(this.testCopies.fetch(authority, copyId, request));
|
|
735
|
+
});
|
|
736
|
+
}
|
|
737
|
+
catch (cause) {
|
|
738
|
+
return Response.json({ error: cause instanceof AppInstanceError ? cause.code : "failed" }, { status: cause instanceof AppInstanceError ? 403 : 502 });
|
|
739
|
+
}
|
|
740
|
+
}
|
|
741
|
+
/** Declared methods share copy isolation, never a live invocation frame or binding env. */
|
|
742
|
+
callTestCopy(authority, copyId, name, input, caller, limits, tenantId = defaultTenant) {
|
|
743
|
+
this.requireTenant(tenantId);
|
|
744
|
+
return this.frames.exclusive(() => {
|
|
745
|
+
this.runtimeFor(limits);
|
|
746
|
+
return result(this.testCopies.call(authority, copyId, name, input, caller));
|
|
747
|
+
});
|
|
748
|
+
}
|
|
658
749
|
/** The deployable root's host for one pinned tenant; this plain root is the single owner key. */
|
|
659
750
|
hostFor(scope) {
|
|
660
751
|
return Promise.resolve(ownerKeyRootHost(this.env, { scope }));
|
|
@@ -831,7 +922,14 @@ export class OysterInstance extends DurableObject {
|
|
|
831
922
|
}
|
|
832
923
|
/** Carrier owns retries, dead letters and retained delivery receipts. */
|
|
833
924
|
async alarm() {
|
|
834
|
-
|
|
925
|
+
// Neither duty may mask the other; the first failure still surfaces.
|
|
926
|
+
const settled = await Promise.allSettled([
|
|
927
|
+
this.gitJournal.then((journal) => journal.alarm()),
|
|
928
|
+
Effect.runPromise(this.testCopies.expire()),
|
|
929
|
+
]);
|
|
930
|
+
const failed = settled.find((outcome) => outcome.status === "rejected");
|
|
931
|
+
if (failed !== undefined)
|
|
932
|
+
throw failed.reason;
|
|
835
933
|
}
|
|
836
934
|
/** Installation changes end guest work; a Workflow cancel targets only its run. */
|
|
837
935
|
async revoke(installationId, runId, tenantId = defaultTenant) {
|
|
@@ -847,6 +945,8 @@ export class OysterInstance extends DurableObject {
|
|
|
847
945
|
if (installationId !== this.installationId())
|
|
848
946
|
throw new AppInstanceError("instance_owner_mismatch");
|
|
849
947
|
await this.frames.revoke(new AppInstanceError("revoked"), runId === undefined ? undefined : { runId });
|
|
948
|
+
if (runId === undefined)
|
|
949
|
+
await Effect.runPromise(this.testCopies.revoke());
|
|
850
950
|
}
|
|
851
951
|
/** One registry read re-admits a guest binding packet against its frame. */
|
|
852
952
|
async assertCurrent(frame) {
|
|
@@ -1006,6 +1106,16 @@ export class OysterInstance extends DurableObject {
|
|
|
1006
1106
|
checkTenant();
|
|
1007
1107
|
if (!(await committed()))
|
|
1008
1108
|
return { ok: false, code: "stale_authority" };
|
|
1109
|
+
try {
|
|
1110
|
+
await Effect.runPromise(this.testCopies.revoke());
|
|
1111
|
+
}
|
|
1112
|
+
catch (cause) {
|
|
1113
|
+
// A stuck test copy must not block the selection that retires it:
|
|
1114
|
+
// it stays closing and the alarm's expiry retries the purge.
|
|
1115
|
+
console.error("Oyster: test copy revoke failed during activation", {
|
|
1116
|
+
causeClass: causeClass(cause),
|
|
1117
|
+
});
|
|
1118
|
+
}
|
|
1009
1119
|
// These pins attest the committed owner, not successful activation.
|
|
1010
1120
|
// Persist before boot so a failed first activation can be retried or
|
|
1011
1121
|
// revoked/deleted without ever claiming an active lifecycle receipt.
|
package/docs/api/README.md
CHANGED
|
@@ -148,9 +148,14 @@ installed Apps are cleared once: Oyster Home asks you to reinstall them with
|
|
|
148
148
|
`npx @fungi.computer/oyster install-apps`, which restores the Apps and their App
|
|
149
149
|
settings, while each App's own backend database starts empty. Agents, Sessions,
|
|
150
150
|
files and keys are kept. From 0.2 or earlier, Oyster answers every request with
|
|
151
|
-
`409` and `store_from_older_oyster
|
|
152
|
-
old
|
|
153
|
-
|
|
151
|
+
`409` and `store_from_older_oyster` and leaves the store untouched. Do not tear
|
|
152
|
+
the old Worker down or deploy over it: verify its release first (0.0.1 needs a
|
|
153
|
+
release-matched bridge; 0.1 and 0.2 are archived through their own Worker before
|
|
154
|
+
a fresh setup under new names). A bridge at the old Worker's name accepts only
|
|
155
|
+
the owner's export request and answers everything else `503 oyster_archiving`.
|
|
156
|
+
The archive workflow is still being built and its registry SQL export is not a
|
|
157
|
+
certified archive, so keep the old Worker and its stores until you have one. The
|
|
158
|
+
changelog entry for each release says when it resets data.
|
|
154
159
|
|
|
155
160
|
### Run on celld
|
|
156
161
|
|
package/docs/api/cloudflare.md
CHANGED
|
@@ -149,6 +149,19 @@ Loader memoization and class lookup; entrypoint access is not required.
|
|
|
149
149
|
|
|
150
150
|
---
|
|
151
151
|
|
|
152
|
+
### AppTestCopyBackend
|
|
153
|
+
|
|
154
|
+
```ts
|
|
155
|
+
type AppTestCopyBackend = Backend &
|
|
156
|
+
Readonly<{
|
|
157
|
+
api: AppApi | null;
|
|
158
|
+
}>;
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
Verified code and its declaration travel together at the copy boundary.
|
|
162
|
+
|
|
163
|
+
---
|
|
164
|
+
|
|
152
165
|
### FrameBindingReply
|
|
153
166
|
|
|
154
167
|
```ts
|
|
@@ -454,6 +467,50 @@ _typeof_ `WorkerEntrypoint`
|
|
|
454
467
|
|
|
455
468
|
---
|
|
456
469
|
|
|
470
|
+
### createCloudflareAppTestCopies()
|
|
471
|
+
|
|
472
|
+
```ts
|
|
473
|
+
function createCloudflareAppTestCopies<FacetClass>(
|
|
474
|
+
ctx,
|
|
475
|
+
loader,
|
|
476
|
+
ports,
|
|
477
|
+
limits?,
|
|
478
|
+
): object;
|
|
479
|
+
```
|
|
480
|
+
|
|
481
|
+
Disposable App-data siblings use the same native facade and wire decoder as live
|
|
482
|
+
invocation, but no invocation frame, binding factory or live host env. The
|
|
483
|
+
surrounding Instance owns current authority and shared alarm scheduling.
|
|
484
|
+
|
|
485
|
+
#### Type Parameters
|
|
486
|
+
|
|
487
|
+
| Type Parameter |
|
|
488
|
+
| -------------- |
|
|
489
|
+
| `FacetClass` |
|
|
490
|
+
|
|
491
|
+
#### Parameters
|
|
492
|
+
|
|
493
|
+
| Parameter | Type |
|
|
494
|
+
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
495
|
+
| `ctx` | [`AppInstanceContext`](#appinstancecontext)\<`FacetClass`\> |
|
|
496
|
+
| `loader` | \| `Readonly`\<\{ `get`: (`id`, `configure`) => `Readonly`\<\{ `getDurableObjectClass`: (`exportName`) => `FacetClass`; \}\>; \}\> \| `undefined` |
|
|
497
|
+
| `ports` | `Pick`\<`Readonly`\<\{ `owner`: `WatchdogSqliteOwner`; `now`: () => `number`; `source`: () => `Effect`\< \| `Readonly`\<\{ `instance`: \{ `instanceId`: [`InstanceId`](index.md#instanceid); `owner`: \{ `kind`: ...; `id`: ...; \}; `appId`: `AppId`; `releaseId`: `ReleaseId`; `authorityVersion`: `number`; `stateSchema`: ... \| ...; `desiredStatus`: ... \| ... \| ...; `status`: ... \| ... \| ... \| ...; \}; `storeGeneration`: `string`; \}\> \| `null`, `Error`\>; `clone`: () => `Effect`\<`void`, `Error`\>; `purge`: () => `Effect`\<`void`, `Error`\>; `wake`: (`at`) => `Effect`\<`void`, `Error`\>; \}\>, `"source"` \| `"wake"`\> & `Readonly`\<\{ `limits?`: () => [`GuestLimits`](#guestlimits); `resolve`: (`releaseId`) => `Effect`\<[`AppTestCopyBackend`](#apptestcopybackend), `Error`\>; \}\> |
|
|
498
|
+
| `limits?` | `Partial`\<`Readonly`\<\{ `cpuMs`: `number`; `subRequests`: `number`; \}\>\> |
|
|
499
|
+
|
|
500
|
+
#### Returns
|
|
501
|
+
|
|
502
|
+
| Name | Type | Default value | Description |
|
|
503
|
+
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------ |
|
|
504
|
+
| `open()` | (`authority`, `requestId`) => `Effect`\<\{ `selection`: \{ `instanceId`: [`InstanceId`](index.md#instanceid); `owner`: \{ `kind`: `"installation"` \| `"deployment"`; `id`: `string`; \}; `appId`: `AppId`; `releaseId`: `ReleaseId`; `authorityVersion`: `number`; \}; `storeGeneration`: `string`; `copyId`: `string`; `expiresAt`: `number`; \}, `Error` \| [`AppInstanceError`](index.md#appinstanceerror), `never`\> | - | Clone current App data once under the retained request and fixed deadline. |
|
|
505
|
+
| `inspect()` | (`authority`) => `Effect`\< \| \{ `selection`: \{ `instanceId`: [`InstanceId`](index.md#instanceid); `owner`: \{ `kind`: `"installation"` \| `"deployment"`; `id`: `string`; \}; `appId`: `AppId`; `releaseId`: `ReleaseId`; `authorityVersion`: `number`; \}; `storeGeneration`: `string`; `copyId`: `string`; `expiresAt`: `number`; \} \| `null`, `Error` \| [`AppInstanceError`](index.md#appinstanceerror), `never`\> | - | Observe the sibling, retiring expired or unavailable source selections. |
|
|
506
|
+
| `discard()` | (`authority`, `copyId`) => `Effect`\<`boolean`, `Error`, `never`\> | `copies.discard` | Discard only this resource, retaining its latest request receipt. |
|
|
507
|
+
| `expire()` | () => `Effect`\<`void`, `Error`, `never`\> | `copies.expire` | Shared native alarm cleanup; incomplete phases need no source service. |
|
|
508
|
+
| `revoke()` | () => `Effect`\<`void`, `Error`, `never`\> | `copies.revoke` | Retire the sibling when its owning installation loses authority. |
|
|
509
|
+
| `fetch()` | (`authority`, `copyId`, `request`) => `Effect`\<`Response`, `Error` \| [`AppInstanceError`](index.md#appinstanceerror), `never`\> | - | Run ordinary backend HTTP with bounded bodies and no live bindings. |
|
|
510
|
+
| `call()` | (`authority`, `copyId`, `method`, `input`, `caller`) => `Effect`\< \| \{ `kind`: `"ok"`; `value`: `JSONType`; \} \| \{ `kind`: `"refused"`; `code`: `"invalid"` \| `"unavailable"` \| `"conflict"` \| `"forbidden"` \| `"not_found"`; `message`: `string`; \}, `Error` \| [`AppInstanceError`](index.md#appinstanceerror), `never`\> | - | Use the ordinary typed facade and verified method codecs, without live grants. |
|
|
511
|
+
|
|
512
|
+
---
|
|
513
|
+
|
|
457
514
|
### createCloudflareInvocationGate()
|
|
458
515
|
|
|
459
516
|
```ts
|
package/docs/api/host.md
CHANGED
|
@@ -74,6 +74,26 @@ readonly code:
|
|
|
74
74
|
|
|
75
75
|
## Type Aliases
|
|
76
76
|
|
|
77
|
+
### AppTestCopyAuthority
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
type AppTestCopyAuthority = z.output<typeof appTestCopyAuthoritySchema>;
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Exact source selection and store incarnation observed by the owner.
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
### AppTestCopy
|
|
88
|
+
|
|
89
|
+
```ts
|
|
90
|
+
type AppTestCopy = z.output<typeof appTestCopySchema>;
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Observed sibling identity and nonrenewing deadline, never live host grants.
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
77
97
|
### CapabilityMethodKind
|
|
78
98
|
|
|
79
99
|
```ts
|
|
@@ -214,6 +234,19 @@ The result of one Instance operation; refusals carry Oyster's error code.
|
|
|
214
234
|
|
|
215
235
|
```ts
|
|
216
236
|
type InstanceHandle = Readonly<{
|
|
237
|
+
testCopies?: Readonly<{
|
|
238
|
+
open: (authority, requestId) => Promise<InstanceResult<AppTestCopy>>;
|
|
239
|
+
inspect: (authority) => Promise<InstanceResult<AppTestCopy | null>>;
|
|
240
|
+
discard: (authority, copyId) => Promise<InstanceResult<boolean>>;
|
|
241
|
+
fetch: (authority, copyId, request) => Promise<Response>;
|
|
242
|
+
call: (
|
|
243
|
+
authority,
|
|
244
|
+
copyId,
|
|
245
|
+
name,
|
|
246
|
+
input,
|
|
247
|
+
caller,
|
|
248
|
+
) => Promise<InstanceResult<AppMethodReply>>;
|
|
249
|
+
}>;
|
|
217
250
|
prepare: (
|
|
218
251
|
state,
|
|
219
252
|
release,
|
|
@@ -500,6 +533,60 @@ One host's declared routes and the one way to serve them.
|
|
|
500
533
|
|
|
501
534
|
```ts
|
|
502
535
|
type InstallationOperations = Readonly<{
|
|
536
|
+
recovery: Promise<
|
|
537
|
+
| {
|
|
538
|
+
authorityVersion: number;
|
|
539
|
+
storeGeneration: string;
|
|
540
|
+
release: {
|
|
541
|
+
releaseId: Schema.refine<ReleaseId, Schema.String>;
|
|
542
|
+
appId: Schema.refine<AppId, Schema.String>;
|
|
543
|
+
artifact: Schema.Struct<{
|
|
544
|
+
artifactRef: Schema.refine<ArtifactRef, Schema.String>;
|
|
545
|
+
artifactDigest: Schema.refine<Sha256Digest, Schema.String>;
|
|
546
|
+
provenance: Schema.Struct<{
|
|
547
|
+
sourceRevision: Schema.refine<..., ...>;
|
|
548
|
+
sourceTreeDigest: Schema.refine<..., ...>;
|
|
549
|
+
buildRecipeDigest: Schema.refine<..., ...>;
|
|
550
|
+
}>;
|
|
551
|
+
}>;
|
|
552
|
+
};
|
|
553
|
+
uiCheck: | {
|
|
554
|
+
kind: "passed";
|
|
555
|
+
}
|
|
556
|
+
| {
|
|
557
|
+
kind: "failed";
|
|
558
|
+
code: "ui_mount_failed";
|
|
559
|
+
diagnostics?: {
|
|
560
|
+
failedPredicate: | "unexpected_candidate_request"
|
|
561
|
+
| "response_status"
|
|
562
|
+
| "request_failed"
|
|
563
|
+
| "page_error"
|
|
564
|
+
| "candidate_not_mounted";
|
|
565
|
+
errorName?: | "Error"
|
|
566
|
+
| "TypeError"
|
|
567
|
+
| "RangeError"
|
|
568
|
+
| "SyntaxError"
|
|
569
|
+
| "AbortError"
|
|
570
|
+
| "TimeoutError"
|
|
571
|
+
| "Other";
|
|
572
|
+
finalUrlPath: string;
|
|
573
|
+
consoleErrors: string[];
|
|
574
|
+
pageErrors: string[];
|
|
575
|
+
failedRequests: object[];
|
|
576
|
+
droppedCount: number;
|
|
577
|
+
};
|
|
578
|
+
}
|
|
579
|
+
| {
|
|
580
|
+
kind: "not_checked";
|
|
581
|
+
code: | "boot_runner_unavailable"
|
|
582
|
+
| "boot_browser_binding_missing"
|
|
583
|
+
| "boot_clone_unavailable"
|
|
584
|
+
| "boot_timeout"
|
|
585
|
+
| "boot_cleanup_failed"
|
|
586
|
+
| "ui_check_not_run_on_host";
|
|
587
|
+
};
|
|
588
|
+
}
|
|
589
|
+
| null>;
|
|
503
590
|
admit: Promise<
|
|
504
591
|
| {
|
|
505
592
|
requestId: string;
|
|
@@ -975,20 +1062,16 @@ type InstallationOperations = Readonly<{
|
|
|
975
1062
|
| null>;
|
|
976
1063
|
load: Promise<
|
|
977
1064
|
| {
|
|
978
|
-
admission: {
|
|
1065
|
+
admission: | {
|
|
979
1066
|
requestId: string;
|
|
980
1067
|
installationId: string;
|
|
981
1068
|
release: {
|
|
982
1069
|
releaseId: Schema.refine<ReleaseId, Schema.String>;
|
|
983
1070
|
appId: Schema.refine<AppId, Schema.String>;
|
|
984
1071
|
artifact: Schema.Struct<{
|
|
985
|
-
artifactRef: Schema.refine
|
|
986
|
-
artifactDigest: Schema.refine
|
|
987
|
-
provenance: Schema.Struct
|
|
988
|
-
sourceRevision: ...;
|
|
989
|
-
sourceTreeDigest: ...;
|
|
990
|
-
buildRecipeDigest: ...;
|
|
991
|
-
}>;
|
|
1072
|
+
artifactRef: Schema.refine<..., ...>;
|
|
1073
|
+
artifactDigest: Schema.refine<..., ...>;
|
|
1074
|
+
provenance: Schema.Struct<...>;
|
|
992
1075
|
}>;
|
|
993
1076
|
};
|
|
994
1077
|
actor: | {
|
|
@@ -1005,7 +1088,36 @@ type InstallationOperations = Readonly<{
|
|
|
1005
1088
|
};
|
|
1006
1089
|
intent: "install-or-select" | "install-or-remint" | "create-only";
|
|
1007
1090
|
origin: "workflow" | "owner-direct";
|
|
1008
|
-
|
|
1091
|
+
}
|
|
1092
|
+
| {
|
|
1093
|
+
authorityVersion: number;
|
|
1094
|
+
storeGeneration: string;
|
|
1095
|
+
requestId: string;
|
|
1096
|
+
installationId: string;
|
|
1097
|
+
actor: | {
|
|
1098
|
+
kind: z.ZodMiniLiteral<"member">;
|
|
1099
|
+
memberId: z.ZodMiniString<string>;
|
|
1100
|
+
}
|
|
1101
|
+
| {
|
|
1102
|
+
kind: z.ZodMiniLiteral<"agent">;
|
|
1103
|
+
agentId: z.ZodMiniString<string>;
|
|
1104
|
+
}
|
|
1105
|
+
| {
|
|
1106
|
+
kind: z.ZodMiniLiteral<"team-key">;
|
|
1107
|
+
keyId: z.ZodMiniString<string>;
|
|
1108
|
+
};
|
|
1109
|
+
intent: "rollback";
|
|
1110
|
+
origin: "owner-direct";
|
|
1111
|
+
release: {
|
|
1112
|
+
releaseId: Schema.refine<ReleaseId, Schema.String>;
|
|
1113
|
+
appId: Schema.refine<AppId, Schema.String>;
|
|
1114
|
+
artifact: Schema.Struct<{
|
|
1115
|
+
artifactRef: Schema.refine<..., ...>;
|
|
1116
|
+
artifactDigest: Schema.refine<..., ...>;
|
|
1117
|
+
provenance: Schema.Struct<...>;
|
|
1118
|
+
}>;
|
|
1119
|
+
};
|
|
1120
|
+
};
|
|
1009
1121
|
scope: {
|
|
1010
1122
|
tenantId: string & Brand<"OysterTenantId">;
|
|
1011
1123
|
origin: string;
|
|
@@ -1124,7 +1236,7 @@ type InstallationOperations = Readonly<{
|
|
|
1124
1236
|
}
|
|
1125
1237
|
| null>;
|
|
1126
1238
|
plan: Promise<{
|
|
1127
|
-
admission: {
|
|
1239
|
+
admission: | {
|
|
1128
1240
|
requestId: string;
|
|
1129
1241
|
installationId: string;
|
|
1130
1242
|
release: {
|
|
@@ -1134,9 +1246,9 @@ type InstallationOperations = Readonly<{
|
|
|
1134
1246
|
artifactRef: Schema.refine<ArtifactRef, Schema.String>;
|
|
1135
1247
|
artifactDigest: Schema.refine<Sha256Digest, Schema.String>;
|
|
1136
1248
|
provenance: Schema.Struct<{
|
|
1137
|
-
sourceRevision:
|
|
1138
|
-
sourceTreeDigest:
|
|
1139
|
-
buildRecipeDigest:
|
|
1249
|
+
sourceRevision: ...;
|
|
1250
|
+
sourceTreeDigest: ...;
|
|
1251
|
+
buildRecipeDigest: ...;
|
|
1140
1252
|
}>;
|
|
1141
1253
|
}>;
|
|
1142
1254
|
};
|
|
@@ -1154,7 +1266,40 @@ type InstallationOperations = Readonly<{
|
|
|
1154
1266
|
};
|
|
1155
1267
|
intent: "install-or-select" | "install-or-remint" | "create-only";
|
|
1156
1268
|
origin: "workflow" | "owner-direct";
|
|
1157
|
-
|
|
1269
|
+
}
|
|
1270
|
+
| {
|
|
1271
|
+
authorityVersion: number;
|
|
1272
|
+
storeGeneration: string;
|
|
1273
|
+
requestId: string;
|
|
1274
|
+
installationId: string;
|
|
1275
|
+
actor: | {
|
|
1276
|
+
kind: z.ZodMiniLiteral<"member">;
|
|
1277
|
+
memberId: z.ZodMiniString<string>;
|
|
1278
|
+
}
|
|
1279
|
+
| {
|
|
1280
|
+
kind: z.ZodMiniLiteral<"agent">;
|
|
1281
|
+
agentId: z.ZodMiniString<string>;
|
|
1282
|
+
}
|
|
1283
|
+
| {
|
|
1284
|
+
kind: z.ZodMiniLiteral<"team-key">;
|
|
1285
|
+
keyId: z.ZodMiniString<string>;
|
|
1286
|
+
};
|
|
1287
|
+
intent: "rollback";
|
|
1288
|
+
origin: "owner-direct";
|
|
1289
|
+
release: {
|
|
1290
|
+
releaseId: Schema.refine<ReleaseId, Schema.String>;
|
|
1291
|
+
appId: Schema.refine<AppId, Schema.String>;
|
|
1292
|
+
artifact: Schema.Struct<{
|
|
1293
|
+
artifactRef: Schema.refine<ArtifactRef, Schema.String>;
|
|
1294
|
+
artifactDigest: Schema.refine<Sha256Digest, Schema.String>;
|
|
1295
|
+
provenance: Schema.Struct<{
|
|
1296
|
+
sourceRevision: ...;
|
|
1297
|
+
sourceTreeDigest: ...;
|
|
1298
|
+
buildRecipeDigest: ...;
|
|
1299
|
+
}>;
|
|
1300
|
+
}>;
|
|
1301
|
+
};
|
|
1302
|
+
};
|
|
1158
1303
|
scope: {
|
|
1159
1304
|
tenantId: string & Brand<"OysterTenantId">;
|
|
1160
1305
|
origin: string;
|
|
@@ -1382,6 +1527,70 @@ another store read or hash.
|
|
|
1382
1527
|
|
|
1383
1528
|
## Variables
|
|
1384
1529
|
|
|
1530
|
+
### appTestCopyAuthoritySchema
|
|
1531
|
+
|
|
1532
|
+
```ts
|
|
1533
|
+
const appTestCopyAuthoritySchema: ZodObject<
|
|
1534
|
+
{
|
|
1535
|
+
selection: ZodPipe<
|
|
1536
|
+
ZodUnknown,
|
|
1537
|
+
ZodTransform<
|
|
1538
|
+
{
|
|
1539
|
+
instanceId: InstanceId;
|
|
1540
|
+
owner: {
|
|
1541
|
+
kind: "installation" | "deployment";
|
|
1542
|
+
id: string;
|
|
1543
|
+
};
|
|
1544
|
+
appId: AppId;
|
|
1545
|
+
releaseId: ReleaseId;
|
|
1546
|
+
authorityVersion: number;
|
|
1547
|
+
},
|
|
1548
|
+
unknown
|
|
1549
|
+
>
|
|
1550
|
+
>;
|
|
1551
|
+
storeGeneration: ZodString;
|
|
1552
|
+
},
|
|
1553
|
+
$strict
|
|
1554
|
+
>;
|
|
1555
|
+
```
|
|
1556
|
+
|
|
1557
|
+
A test copy is fenced to the same store and owner selection as its source.
|
|
1558
|
+
|
|
1559
|
+
---
|
|
1560
|
+
|
|
1561
|
+
### appTestCopySchema
|
|
1562
|
+
|
|
1563
|
+
```ts
|
|
1564
|
+
const appTestCopySchema: ZodObject<
|
|
1565
|
+
{
|
|
1566
|
+
selection: ZodPipe<
|
|
1567
|
+
ZodUnknown,
|
|
1568
|
+
ZodTransform<
|
|
1569
|
+
{
|
|
1570
|
+
instanceId: InstanceId;
|
|
1571
|
+
owner: {
|
|
1572
|
+
kind: "installation" | "deployment";
|
|
1573
|
+
id: string;
|
|
1574
|
+
};
|
|
1575
|
+
appId: AppId;
|
|
1576
|
+
releaseId: ReleaseId;
|
|
1577
|
+
authorityVersion: number;
|
|
1578
|
+
},
|
|
1579
|
+
unknown
|
|
1580
|
+
>
|
|
1581
|
+
>;
|
|
1582
|
+
storeGeneration: ZodString;
|
|
1583
|
+
copyId: ZodString;
|
|
1584
|
+
expiresAt: ZodNumber;
|
|
1585
|
+
},
|
|
1586
|
+
$strict
|
|
1587
|
+
>;
|
|
1588
|
+
```
|
|
1589
|
+
|
|
1590
|
+
Host-owned identity and fixed deadline of one disposable App-data sibling.
|
|
1591
|
+
|
|
1592
|
+
---
|
|
1593
|
+
|
|
1385
1594
|
### capabilityMethodKindSchema
|
|
1386
1595
|
|
|
1387
1596
|
```ts
|