@fungi.computer/oyster 0.47.3 → 0.47.5

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.
@@ -0,0 +1,47 @@
1
+ import type { AppFailureReason } from "@fungi.computer/agar/backend";
2
+ import type { FrameBindingMethod } from "./cloudflare.js";
3
+ /**
4
+ * Why one invocation failed on the host's side, written by the frame owner and
5
+ * read by the same invocation when its guest call rejects. Only host-known
6
+ * names and a field path: a failure that crossed the guest facet is never
7
+ * trusted for text.
8
+ */
9
+ export type FrameFailure = Readonly<{
10
+ reason: Extract<AppFailureReason, "binding_reply_invalid">;
11
+ binding: string;
12
+ method: string;
13
+ path: string;
14
+ }>;
15
+ /** One slot per invocation; the first host failure wins. */
16
+ export type FrameFailureSlot = Readonly<{
17
+ /** Keep this failure unless the frame already holds one. */
18
+ record(failure: FrameFailure): void;
19
+ /** The first recorded failure, if any. */
20
+ read(): FrameFailure | undefined;
21
+ }>;
22
+ /** A fresh, empty failure slot for one invocation. */
23
+ export declare function createFrameFailureSlot(): FrameFailureSlot;
24
+ /** The field a reply decoder rejected: the deepest path among its (nested union) issues. */
25
+ export declare function rejectedFieldPath(cause: Error): string;
26
+ /**
27
+ * Decode one connection reply with its method's descriptor: the only place a
28
+ * reply is decoded, where it first arrives and the frame that asked is in
29
+ * hand. A reply the descriptor rejects is our bug, not the App's: it is
30
+ * recorded on the frame (and named in the log, never its values) before the
31
+ * exception reaches the guest, which cannot be trusted to say why. `logged`
32
+ * names the frame and invocation in that log line.
33
+ */
34
+ export declare function decodeBindingReply<Result>(descriptor: Pick<FrameBindingMethod<Result>, "decodeResult">, call: Readonly<{
35
+ binding: string;
36
+ method: string;
37
+ }>, reply: Parameters<FrameBindingMethod<Result>["decodeResult"]>[0], failure: FrameFailureSlot, logged: Readonly<Record<string, string | null>>): Result;
38
+ /**
39
+ * The host failed this invocation for a reason it recorded on the frame. It is
40
+ * built by the frame owner after the guest call rejects, so its reason is the
41
+ * host's own and never text that crossed the guest facet.
42
+ */
43
+ export declare class FrameFailureError extends Error {
44
+ readonly failure: FrameFailure;
45
+ readonly ref: string;
46
+ constructor(failure: FrameFailure, ref: string, options: ErrorOptions);
47
+ }
@@ -0,0 +1,75 @@
1
+ import { z } from "zod";
2
+ /** A fresh, empty failure slot for one invocation. */
3
+ export function createFrameFailureSlot() {
4
+ let held;
5
+ return {
6
+ record(failure) {
7
+ held ??= failure;
8
+ },
9
+ read: () => held,
10
+ };
11
+ }
12
+ /** The field a reply decoder rejected: the deepest path among its (nested union) issues. */
13
+ export function rejectedFieldPath(cause) {
14
+ if (!(cause instanceof z.ZodError))
15
+ return "";
16
+ const paths = [];
17
+ const collect = (issues, prefix) => {
18
+ for (const issue of issues) {
19
+ const path = [...prefix, ...issue.path.map(String)];
20
+ if (issue.code === "invalid_union") {
21
+ for (const branch of issue.errors)
22
+ collect(branch, path);
23
+ }
24
+ else
25
+ paths.push(path);
26
+ }
27
+ };
28
+ collect(cause.issues, []);
29
+ const deepest = paths.reduce((best, path) => (path.length > best.length ? path : best), []);
30
+ return deepest.join(".").slice(0, 256);
31
+ }
32
+ /**
33
+ * Decode one connection reply with its method's descriptor: the only place a
34
+ * reply is decoded, where it first arrives and the frame that asked is in
35
+ * hand. A reply the descriptor rejects is our bug, not the App's: it is
36
+ * recorded on the frame (and named in the log, never its values) before the
37
+ * exception reaches the guest, which cannot be trusted to say why. `logged`
38
+ * names the frame and invocation in that log line.
39
+ */
40
+ export function decodeBindingReply(descriptor, call, reply, failure, logged) {
41
+ try {
42
+ return descriptor.decodeResult(reply);
43
+ }
44
+ catch (cause) {
45
+ const path = cause instanceof Error ? rejectedFieldPath(cause) : "";
46
+ failure.record({
47
+ reason: "binding_reply_invalid",
48
+ binding: call.binding,
49
+ method: call.method,
50
+ path,
51
+ });
52
+ console.error("App binding reply invalid", {
53
+ binding: call.binding,
54
+ method: call.method,
55
+ path,
56
+ ...logged,
57
+ });
58
+ throw cause;
59
+ }
60
+ }
61
+ /**
62
+ * The host failed this invocation for a reason it recorded on the frame. It is
63
+ * built by the frame owner after the guest call rejects, so its reason is the
64
+ * host's own and never text that crossed the guest facet.
65
+ */
66
+ export class FrameFailureError extends Error {
67
+ failure;
68
+ ref;
69
+ constructor(failure, ref, options) {
70
+ super(`App connection reply invalid: ${failure.binding}.${failure.method}`, options);
71
+ this.name = "FrameFailureError";
72
+ this.failure = failure;
73
+ this.ref = ref;
74
+ }
75
+ }