@mostra/protocol 0.3.0 → 0.5.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/dist/diagnostics/codes/env.js +2 -2
- package/dist/diagnostics/codes/env.js.map +1 -1
- package/dist/diagnostics/codes/home.js +1 -1
- package/dist/diagnostics/codes/home.js.map +1 -1
- package/dist/diagnostics/codes/host-core.d.ts +1 -0
- package/dist/diagnostics/codes/host-core.js +68 -0
- package/dist/diagnostics/codes/host-core.js.map +1 -0
- package/dist/diagnostics/codes/host.d.ts.map +1 -1
- package/dist/diagnostics/codes/host.js +6 -61
- package/dist/diagnostics/codes/host.js.map +1 -1
- package/dist/diagnostics/codes/index.js +1 -1
- package/dist/index.d.ts +2 -1
- package/dist/index.js +3 -2
- package/dist/receive.d.ts +24 -0
- package/dist/receive.d.ts.map +1 -0
- package/dist/receive.js +137 -0
- package/dist/receive.js.map +1 -0
- package/dist/rpc/error.d.ts +1 -1
- package/dist/rpc/error.d.ts.map +1 -1
- package/dist/rpc/error.js +4 -4
- package/dist/rpc/error.js.map +1 -1
- package/dist/rpc/peer.d.ts +3 -1
- package/dist/rpc/peer.d.ts.map +1 -1
- package/dist/rpc/peer.js +5 -2
- package/dist/rpc/peer.js.map +1 -1
- package/package.json +4 -4
- package/src/diagnostics/codes/env.ts +2 -2
- package/src/diagnostics/codes/home.ts +1 -1
- package/src/diagnostics/codes/host-core.ts +87 -0
- package/src/diagnostics/codes/host.ts +6 -67
- package/src/index.ts +1 -0
- package/src/receive.ts +176 -0
- package/src/rpc/error.ts +8 -5
- package/src/rpc/peer.ts +5 -2
package/src/receive.ts
ADDED
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Reading what a newer peer sends (HO-07, D32, #45). Within a revision a peer may add values to an
|
|
3
|
+
* enum and members to a union: the wire schemas' evolution rule counts both as additive
|
|
4
|
+
* (`tools/schemas/compat.ts`). A receiver checking such a message against the schemas it was built
|
|
5
|
+
* with would refuse the whole message for one value it doesn't know, so it checks it against
|
|
6
|
+
* {@link receivable}'s copy instead, as the Rust crate's wire types read an `Unknown` variant.
|
|
7
|
+
*/
|
|
8
|
+
import * as z from "zod";
|
|
9
|
+
|
|
10
|
+
/** A Zod node's definition, as far as {@link receivable} reads it. */
|
|
11
|
+
interface Def {
|
|
12
|
+
readonly type: string;
|
|
13
|
+
readonly [key: string]: unknown;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
const opened = new WeakMap<z.ZodType, z.ZodType>();
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* `schema` as a receiver of a newer peer's messages checks it: every string enum and every union
|
|
20
|
+
* of string literals accepts any string (an enum's own checks still run, and an enum-keyed record
|
|
21
|
+
* still needs every key it names); a discriminated union accepts, besides its members, an object
|
|
22
|
+
* whose discriminator is a string none of them has, kept whole; strict objects drop unknown fields
|
|
23
|
+
* rather than refuse them. Everything else (fields, types, required members, limits) is checked as
|
|
24
|
+
* before, so a message a newer peer couldn't have sent still fails, and a message `schema` accepts
|
|
25
|
+
* reads exactly as `schema` reads it: a union tries its members as built before their opened
|
|
26
|
+
* copies, and a discriminated union's members keep their own tags.
|
|
27
|
+
*
|
|
28
|
+
* The result keeps `schema`'s TypeScript type, the shape this side was built for: a value the type
|
|
29
|
+
* doesn't name means a newer peer. Code that branches on such a field handles the other case, and
|
|
30
|
+
* a gate (a verdict, a check, a delivery) passes only on a value it knows means passing, never on
|
|
31
|
+
* the absence of the one it knows means failing.
|
|
32
|
+
*
|
|
33
|
+
* ```ts
|
|
34
|
+
* const parsed = receivable(definition.result).safeParse(raw);
|
|
35
|
+
* ```
|
|
36
|
+
*/
|
|
37
|
+
export function receivable<T>(schema: z.ZodType<T>): z.ZodType<T> {
|
|
38
|
+
return open(schema) as z.ZodType<T>;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
function open(schema: z.ZodType): z.ZodType {
|
|
42
|
+
const known = opened.get(schema);
|
|
43
|
+
if (known) return known;
|
|
44
|
+
// A recursive schema (Zod's getter idiom) reaches itself while it is being opened: it finds this
|
|
45
|
+
// stand-in, which reads the finished copy when a message is checked (Opus review of MT-01, 7).
|
|
46
|
+
let result: z.ZodType | undefined;
|
|
47
|
+
opened.set(
|
|
48
|
+
schema,
|
|
49
|
+
z.lazy(() => result ?? schema),
|
|
50
|
+
);
|
|
51
|
+
result = rebuild(schema);
|
|
52
|
+
opened.set(schema, result);
|
|
53
|
+
return result;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** Any string, with the checks `schema` carries (an enum's `.refine`, say). */
|
|
57
|
+
function anyString(schema: z.ZodType): z.ZodType {
|
|
58
|
+
const checks = defOf(schema)["checks"] as unknown[] | undefined;
|
|
59
|
+
return checks?.length ? cloned(z.string(), { checks }) : z.string();
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
function defOf(schema: z.ZodType): Def {
|
|
63
|
+
return (schema as unknown as { _zod: { def: Def } })._zod.def;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** A copy of `schema` with some of its definition replaced; its checks and settings stay. */
|
|
67
|
+
function cloned(schema: z.ZodType, changes: Record<string, unknown>): z.ZodType {
|
|
68
|
+
return (schema as unknown as { clone(def: Def): z.ZodType }).clone({
|
|
69
|
+
...defOf(schema),
|
|
70
|
+
...changes,
|
|
71
|
+
});
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/** The string values of a literal or enum node, or undefined when it has others. */
|
|
75
|
+
function strings(schema: z.ZodType): string[] | undefined {
|
|
76
|
+
const def = defOf(schema);
|
|
77
|
+
const values =
|
|
78
|
+
def.type === "literal"
|
|
79
|
+
? (def["values"] as unknown[])
|
|
80
|
+
: def.type === "enum"
|
|
81
|
+
? Object.values(def["entries"] as Record<string, unknown>)
|
|
82
|
+
: undefined;
|
|
83
|
+
return values?.every((value) => typeof value === "string") ? (values as string[]) : undefined;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
function rebuild(schema: z.ZodType): z.ZodType {
|
|
87
|
+
const def = defOf(schema);
|
|
88
|
+
switch (def.type) {
|
|
89
|
+
case "enum":
|
|
90
|
+
return strings(schema) ? anyString(schema) : schema;
|
|
91
|
+
case "optional":
|
|
92
|
+
case "nullable":
|
|
93
|
+
case "readonly":
|
|
94
|
+
case "default":
|
|
95
|
+
case "prefault":
|
|
96
|
+
case "nonoptional":
|
|
97
|
+
case "catch":
|
|
98
|
+
return cloned(schema, { innerType: open(def["innerType"] as z.ZodType) });
|
|
99
|
+
case "array":
|
|
100
|
+
return cloned(schema, { element: open(def["element"] as z.ZodType) });
|
|
101
|
+
case "object": {
|
|
102
|
+
const shape = def["shape"] as Record<string, z.ZodType>;
|
|
103
|
+
const catchall = def["catchall"] as z.ZodType | undefined;
|
|
104
|
+
return cloned(schema, {
|
|
105
|
+
shape: Object.fromEntries(Object.entries(shape).map(([key, value]) => [key, open(value)])),
|
|
106
|
+
// A strict object (catchall `never`) would refuse a field a newer peer adds: it is dropped
|
|
107
|
+
// instead. A loose object keeps passing its fields through, and a typed catchall keeps
|
|
108
|
+
// checking them (GPT review of MT-01: the bridge's host context passes fields through).
|
|
109
|
+
catchall:
|
|
110
|
+
catchall === undefined || defOf(catchall).type === "never" ? undefined : open(catchall),
|
|
111
|
+
});
|
|
112
|
+
}
|
|
113
|
+
case "record": {
|
|
114
|
+
const keyType = def["keyType"] as z.ZodType;
|
|
115
|
+
// Keys from an enum: every one it names is still required, and a key a newer peer adds
|
|
116
|
+
// passes through, as Zod's loose records do (Opus review of MT-01, 2).
|
|
117
|
+
if (strings(keyType) && !def["partial"]) {
|
|
118
|
+
return cloned(schema, { valueType: open(def["valueType"] as z.ZodType), mode: "loose" });
|
|
119
|
+
}
|
|
120
|
+
return cloned(schema, {
|
|
121
|
+
keyType: open(keyType),
|
|
122
|
+
valueType: open(def["valueType"] as z.ZodType),
|
|
123
|
+
});
|
|
124
|
+
}
|
|
125
|
+
case "tuple":
|
|
126
|
+
return cloned(schema, {
|
|
127
|
+
items: (def["items"] as z.ZodType[]).map(open),
|
|
128
|
+
rest: def["rest"] ? open(def["rest"] as z.ZodType) : def["rest"],
|
|
129
|
+
});
|
|
130
|
+
case "intersection":
|
|
131
|
+
return cloned(schema, {
|
|
132
|
+
left: open(def["left"] as z.ZodType),
|
|
133
|
+
right: open(def["right"] as z.ZodType),
|
|
134
|
+
});
|
|
135
|
+
case "pipe":
|
|
136
|
+
return cloned(schema, { in: open(def["in"] as z.ZodType) });
|
|
137
|
+
case "lazy": {
|
|
138
|
+
const getter = def["getter"] as () => z.ZodType;
|
|
139
|
+
return z.lazy(() => open(getter()));
|
|
140
|
+
}
|
|
141
|
+
case "union":
|
|
142
|
+
return union(schema, def);
|
|
143
|
+
default:
|
|
144
|
+
return schema;
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
function union(schema: z.ZodType, def: Def): z.ZodType {
|
|
149
|
+
const options = def["options"] as z.ZodType[];
|
|
150
|
+
// A union of string literals is an enum written another way.
|
|
151
|
+
if (options.every((option) => strings(option) !== undefined)) return anyString(schema);
|
|
152
|
+
// The members as built come first, so whatever they accept reads as before; their opened copies
|
|
153
|
+
// only take what none of them does (Opus review of MT-01, 1).
|
|
154
|
+
const anyOf = (members: z.ZodType[]): z.ZodType =>
|
|
155
|
+
z.union([...options, ...members] as [z.ZodType, ...z.ZodType[]]);
|
|
156
|
+
const discriminator = def["discriminator"] as string | undefined;
|
|
157
|
+
if (discriminator === undefined) return anyOf(options.map(open));
|
|
158
|
+
const tags = new Set<string>();
|
|
159
|
+
const members: z.ZodType[] = [];
|
|
160
|
+
for (const option of options) {
|
|
161
|
+
const shape = defOf(option)["shape"] as Record<string, z.ZodType> | undefined;
|
|
162
|
+
const tag = shape?.[discriminator];
|
|
163
|
+
const values = tag ? strings(tag) : undefined;
|
|
164
|
+
// A member whose tag isn't a string literal: no newer member can be told from a broken one.
|
|
165
|
+
if (!tag || !values) return anyOf(options.map(open));
|
|
166
|
+
for (const value of values) tags.add(value);
|
|
167
|
+
// An opened member keeps its own tag: widened, an enum tag would take every member's messages.
|
|
168
|
+
const member = open(option);
|
|
169
|
+
const memberShape = defOf(member)["shape"] as Record<string, z.ZodType>;
|
|
170
|
+
members.push(cloned(member, { shape: { ...memberShape, [discriminator]: tag } }));
|
|
171
|
+
}
|
|
172
|
+
const newer = z.looseObject({
|
|
173
|
+
[discriminator]: z.string().refine((value) => !tags.has(value)),
|
|
174
|
+
});
|
|
175
|
+
return anyOf([...members, newer]);
|
|
176
|
+
}
|
package/src/rpc/error.ts
CHANGED
|
@@ -2,7 +2,10 @@
|
|
|
2
2
|
* Errors on a JSON-RPC connection. Every error carries a diagnostic (INTERFACES §1, §6): the
|
|
3
3
|
* JSON-RPC `error.code` says which kind of failure it is, and `error.data` is the diagnostic.
|
|
4
4
|
*/
|
|
5
|
-
import {
|
|
5
|
+
import {
|
|
6
|
+
type CoreHostDiagnosticCode,
|
|
7
|
+
coreHostDiagnostics,
|
|
8
|
+
} from "../diagnostics/codes/host-core.ts";
|
|
6
9
|
import { Diagnostic } from "../diagnostics/diagnostic.ts";
|
|
7
10
|
import { buildDiagnostic, type DiagnosticDetails } from "../diagnostics/spec.ts";
|
|
8
11
|
import type { JsonRpcErrorObject } from "./messages.ts";
|
|
@@ -95,13 +98,13 @@ export class RpcError extends Error {
|
|
|
95
98
|
}
|
|
96
99
|
|
|
97
100
|
/**
|
|
98
|
-
* Builds
|
|
99
|
-
*
|
|
101
|
+
* Builds one of the HOST-area diagnostics the JSON-RPC core raises, from their own catalog, so the
|
|
102
|
+
* core pulls neither the other areas' text nor the rest of HOST's into browser bundles (D83, #17).
|
|
100
103
|
*/
|
|
101
104
|
export function hostDiagnostic(
|
|
102
|
-
code:
|
|
105
|
+
code: CoreHostDiagnosticCode,
|
|
103
106
|
details: DiagnosticDetails,
|
|
104
107
|
docsBase?: string,
|
|
105
108
|
): Diagnostic {
|
|
106
|
-
return buildDiagnostic(code,
|
|
109
|
+
return buildDiagnostic(code, coreHostDiagnostics[code], details, docsBase);
|
|
107
110
|
}
|
package/src/rpc/peer.ts
CHANGED
|
@@ -15,6 +15,7 @@
|
|
|
15
15
|
*/
|
|
16
16
|
import type { Diagnostic } from "../diagnostics/diagnostic.ts";
|
|
17
17
|
import type { MethodDefinition } from "../method.ts";
|
|
18
|
+
import { receivable } from "../receive.ts";
|
|
18
19
|
import { hostDiagnostic, JSON_RPC_ERROR_CODES, RpcError } from "./error.ts";
|
|
19
20
|
import {
|
|
20
21
|
classifyMessage,
|
|
@@ -185,7 +186,9 @@ export class RpcPeer {
|
|
|
185
186
|
|
|
186
187
|
/**
|
|
187
188
|
* Calls a protocol method: validates the params before sending and the result on arrival. A
|
|
188
|
-
* result that fails the method's schema rejects with `MOSTRA_HOST_MALFORMED`.
|
|
189
|
+
* result that fails the method's schema rejects with `MOSTRA_HOST_MALFORMED`. The result is
|
|
190
|
+
* read as {@link receivable} reads it, so an enum value or union member a newer peer added
|
|
191
|
+
* within the revision arrives as sent (#45).
|
|
189
192
|
*/
|
|
190
193
|
async call<P, R>(
|
|
191
194
|
definition: MethodDefinition<P, R>,
|
|
@@ -194,7 +197,7 @@ export class RpcPeer {
|
|
|
194
197
|
): Promise<R> {
|
|
195
198
|
const checked = parseParams(definition, params, this.#options.docsBase);
|
|
196
199
|
const raw = await this.request(definition.method, checked as JsonRpcParams, options);
|
|
197
|
-
const parsed = definition.result.safeParse(raw);
|
|
200
|
+
const parsed = receivable(definition.result).safeParse(raw);
|
|
198
201
|
if (parsed.success) return parsed.data;
|
|
199
202
|
throw new RpcError(
|
|
200
203
|
this.#diagnostic(
|