Skip to content

Commit ca3f973

Browse files
feat(contracts): clients tolerate union members they don't know yet (pingdotgg#15951)
Co-authored-by: Claude Opus 5.5 (1M context) <[email protected]>
1 parent 51f7f77 commit ca3f973

5 files changed

Lines changed: 472 additions & 31 deletions

File tree

‎apps/server/src/orchestration-v2/ThreadLaunchService.test.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -329,7 +329,10 @@ it.effect.each(
329329
assert.equal(wire.messages[0]?.text, task.prompt);
330330
assert.equal(wire.messages[0]?.scheduledTaskId, task.id);
331331
assert.equal(wire.messages[0]?.createdBy, createdBy);
332-
const turnItem = wire.turnItems.find((item) => item.type === "user_message");
332+
const turnItem = wire.turnItems.find(
333+
(item): item is Extract<typeof item, { type: "user_message" }> =>
334+
item.type === "user_message",
335+
);
333336
assert.equal(turnItem?.text, task.prompt);
334337
assert.equal(turnItem?.scheduledTaskId, task.id);
335338
}).pipe(Effect.provide(Layer.mergeAll(harness.layer, scheduledTasks)));
Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
import { describe, expect, it } from "@effect/vitest";
2+
import * as DateTime from "effect/DateTime";
3+
import * as Effect from "effect/Effect";
4+
import * as Schema from "effect/Schema";
5+
6+
import {
7+
ForwardCompatibleArray,
8+
ForwardCompatibleUnion,
9+
ForwardCompatibleUnionArray,
10+
isUnknownUnionMember,
11+
UnknownUnionMember,
12+
} from "./baseSchemas.ts";
13+
14+
const at = "2026-10-05T00:00:00.000Z";
15+
const Shape = Schema.Union([
16+
Schema.Struct({ kind: Schema.Literal("circle"), radius: Schema.Number, at: Schema.DateTimeUtc }),
17+
Schema.Struct({ kind: Schema.Literal("square"), side: Schema.Number }),
18+
]);
19+
const members = Shape.members;
20+
/** How clients decode: the JSON wire codec over the runtime schema. */
21+
const fromWire = <S extends Schema.Top>(schema: S) =>
22+
Schema.decodeUnknownSync(Schema.toCodecJson(schema) as never) as (value: unknown) => S["Type"];
23+
24+
describe("ForwardCompatibleArray", () => {
25+
it("decodes elements through their own codec and drops ones it cannot read", () => {
26+
const decoded = fromWire(ForwardCompatibleArray(Shape))([
27+
{ kind: "circle", radius: 1, at },
28+
{ kind: "triangle" },
29+
{ kind: "square", side: "wide" },
30+
]);
31+
expect(decoded).toHaveLength(1);
32+
expect(DateTime.isDateTime((decoded[0] as { at: unknown }).at)).toBe(true);
33+
});
34+
35+
it("applies decoding defaults instead of failing", () => {
36+
const WithDefault = Schema.Struct({
37+
name: Schema.String,
38+
count: Schema.optionalKey(Schema.Number).pipe(
39+
Schema.withDecodingDefaultKey(Effect.succeed(7)),
40+
),
41+
});
42+
expect(Schema.decodeUnknownSync(ForwardCompatibleArray(WithDefault))([{ name: "a" }])).toEqual([
43+
{ name: "a", count: 7 },
44+
]);
45+
});
46+
});
47+
48+
describe("ForwardCompatibleUnion", () => {
49+
const decode = fromWire(ForwardCompatibleUnion(members, "kind"));
50+
51+
it("decodes a member from a newer server as unknown", () => {
52+
const decoded = decode({ kind: "triangle", corners: 3 });
53+
expect(isUnknownUnionMember(decoded)).toBe(true);
54+
expect(decoded).toEqual(new UnknownUnionMember("kind", "triangle"));
55+
});
56+
57+
it("decodes known members in full, transformations included", () => {
58+
const decoded = decode({ kind: "circle", radius: 1, at });
59+
expect(isUnknownUnionMember(decoded)).toBe(false);
60+
expect(DateTime.isDateTime((decoded as { at: unknown }).at)).toBe(true);
61+
});
62+
63+
it("still fails a known member whose payload is broken", () => {
64+
expect(() => decode({ kind: "square", side: "wide" })).toThrow();
65+
});
66+
67+
it("refuses to encode an unknown member", () => {
68+
const encode = Schema.encodeSync(ForwardCompatibleUnion(members, "kind") as never);
69+
expect(() => encode(new UnknownUnionMember("kind", "triangle") as never)).toThrow();
70+
});
71+
});
72+
73+
describe("ForwardCompatibleUnionArray", () => {
74+
it("keeps a known member however its fields are named", () => {
75+
const Flagged = Schema.Struct({
76+
kind: Schema.Literal("flag"),
77+
_unknown: Schema.Literal(true),
78+
tag: Schema.String,
79+
value: Schema.String,
80+
});
81+
const flag = { kind: "flag", _unknown: true, tag: "kind", value: "x" };
82+
expect(fromWire(ForwardCompatibleUnionArray([Flagged], "kind"))([flag])).toEqual([flag]);
83+
});
84+
85+
const decode = fromWire(ForwardCompatibleUnionArray(members, "kind"));
86+
87+
it("drops members a newer server added and keeps the rest", () => {
88+
const decoded = decode([
89+
{ kind: "triangle" },
90+
{ kind: "circle", radius: 1, at },
91+
{ kind: "square", side: 2 },
92+
]);
93+
expect(decoded.map((shape) => shape.kind)).toEqual(["circle", "square"]);
94+
});
95+
96+
it("fails when a known member is broken, so real bugs stay visible", () => {
97+
expect(() => decode([{ kind: "square", side: "wide" }])).toThrow();
98+
});
99+
100+
it("encodes as a plain array", () => {
101+
const encode = Schema.encodeSync(
102+
Schema.toCodecJson(ForwardCompatibleUnionArray(members, "kind")),
103+
);
104+
const square = { kind: "square" as const, side: 2 };
105+
expect(encode([square])).toEqual([square]);
106+
});
107+
});

‎packages/contracts/src/baseSchemas.ts‎

Lines changed: 160 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import * as Effect from "effect/Effect";
22
import * as Option from "effect/Option";
33
import * as Schema from "effect/Schema";
4+
import * as SchemaGetter from "effect/SchemaGetter";
45
import * as SchemaTransformation from "effect/SchemaTransformation";
56

67
export const TrimmedString = Schema.String.pipe(
@@ -35,14 +36,6 @@ export type DpopFailureReason = typeof DpopFailureReason.Type;
3536
export const IsoDateTime = Schema.String;
3637
export type IsoDateTime = typeof IsoDateTime.Type;
3738

38-
/**
39-
* Wire codec for server→client arrays whose element unions grow over time
40-
* (new literal members, new struct variants). Decoding drops elements the
41-
* current build cannot decode instead of failing the whole payload — a client
42-
* has to keep decoding configs sent by servers newer than itself, and
43-
* rejecting the payload would take down the connection over data the client
44-
* couldn't act on anyway. Encoding is the plain array encoding.
45-
*/
4639
/**
4740
* Same idea for one optional value whose literal set grows over time: a
4841
* member this build does not know decodes as absent rather than failing the
@@ -107,20 +100,172 @@ export const OmittedWhenNull = <Value extends Schema.Top>(value: Value) => {
107100
);
108101
};
109102

110-
export const ForwardCompatibleArray = <Element extends Schema.Top>(element: Element) => {
111-
const decodeElement = Schema.decodeUnknownOption(element as never);
112-
return Schema.Array(Schema.Unknown).pipe(
103+
/**
104+
* Wire codec for a server→client value whose shape grows over time: a union
105+
* a newer server may add members to, or an array of such values. Clients keep
106+
* decoding payloads from servers newer than themselves instead of failing the
107+
* connection over data they could not act on anyway.
108+
*
109+
* Decoding runs each value through its own schema, so transformations (dates,
110+
* trimming, decoding defaults) apply as usual. Only values that schema
111+
* rejects are dropped; encoding is the plain encoding.
112+
*
113+
* For a tagged union, prefer {@link ForwardCompatibleUnion}: it drops only
114+
* values whose tag this build does not know, so a known member with a broken
115+
* payload still fails loudly.
116+
*/
117+
export const ForwardCompatibleArray = <Element extends Schema.Top>(element: Element) =>
118+
Schema.Array(
119+
Schema.UndefinedOr(element).pipe(
120+
// An element this build cannot read becomes a hole, filtered out below.
121+
Schema.catchDecoding(() => Effect.succeedSome(undefined)),
122+
),
123+
).pipe(
124+
Schema.decodeTo(
125+
Schema.Array(Schema.toType(element)),
126+
SchemaTransformation.transform<
127+
ReadonlyArray<Element["Type"]>,
128+
ReadonlyArray<Element["Type"] | undefined>
129+
>({
130+
decode: (values) => values.filter((value) => value !== undefined),
131+
encode: (values) => values,
132+
}),
133+
),
134+
) as unknown as ForwardCompatibleArray<Element>;
135+
export type ForwardCompatibleArray<Element extends Schema.Top> = Schema.Codec<
136+
ReadonlyArray<Element["Type"]>,
137+
ReadonlyArray<Element["Encoded"]>,
138+
Element["DecodingServices"],
139+
Element["EncodingServices"]
140+
>;
141+
142+
/**
143+
* A member of a {@link ForwardCompatibleUnion} whose tag this build does not
144+
* know. A class, so only the codec can make one: no decoded payload, however
145+
* it is shaped, is ever mistaken for it.
146+
*/
147+
export class UnknownUnionMember<Tag extends string = string> {
148+
readonly tag: Tag;
149+
readonly value: string;
150+
constructor(tag: Tag, value: string) {
151+
this.tag = tag;
152+
this.value = value;
153+
}
154+
}
155+
156+
/**
157+
* Wire codec for a server→client tagged union a newer server may add members
158+
* to. A value whose `tag` field holds a value this build does not know decodes
159+
* to {@link UnknownUnionMember} instead of failing; a known member decodes
160+
* through its own schema, so a broken known payload still fails. Callers
161+
* decide what an unknown member means: skip it, or show a fallback.
162+
*
163+
* Unknown members are decode-only; encoding one fails.
164+
*/
165+
export const ForwardCompatibleUnion = <
166+
const Members extends ReadonlyArray<Schema.Top & { readonly fields: object }>,
167+
const Tag extends string,
168+
>(
169+
members: Members,
170+
tag: Tag,
171+
) => {
172+
const known = knownTags(members, tag);
173+
const unknownMember = Schema.Struct({
174+
[tag]: Schema.String.check(
175+
Schema.makeFilter(
176+
(value: string) => !known.has(value) || `A known ${tag} must decode in full.`,
177+
),
178+
),
179+
} as Record<Tag, Schema.String>).pipe(
180+
Schema.decodeTo(Schema.instanceOf(UnknownUnionMember<Tag>), {
181+
decode: SchemaGetter.transform(
182+
(raw: Record<string, string>) => new UnknownUnionMember(tag, raw[tag]!),
183+
),
184+
encode: SchemaGetter.forbidden(() => `Unknown ${tag} values are never sent.`),
185+
}),
186+
);
187+
return Schema.Union([...members, unknownMember]) as unknown as ForwardCompatibleUnion<
188+
Members,
189+
Tag
190+
>;
191+
};
192+
export type ForwardCompatibleUnion<
193+
Members extends ReadonlyArray<Schema.Top>,
194+
Tag extends string,
195+
> = Schema.Codec<
196+
Members[number]["Type"] | UnknownUnionMember<Tag>,
197+
Members[number]["Encoded"],
198+
Members[number]["DecodingServices"],
199+
Members[number]["EncodingServices"]
200+
>;
201+
202+
/**
203+
* Whether a raw, undecoded value carries a `tag` this build does not know
204+
* among `members`. For checks outside a {@link ForwardCompatibleUnion}, such
205+
* as an envelope that must skip a payload of an unknown kind.
206+
*/
207+
export const hasUnknownUnionTag = (
208+
members: ReadonlyArray<Schema.Top & { readonly fields: object }>,
209+
tag: string,
210+
): ((value: unknown) => boolean) => {
211+
const known = knownTags(members, tag);
212+
return (value) =>
213+
typeof value === "object" &&
214+
value !== null &&
215+
tag in value &&
216+
!known.has((value as Record<string, unknown>)[tag] as string);
217+
};
218+
219+
/** Whether a decoded {@link ForwardCompatibleUnion} value is a member this build does not know. */
220+
export const isUnknownUnionMember = <A>(
221+
value: A,
222+
): value is Extract<A, UnknownUnionMember<string>> => value instanceof UnknownUnionMember;
223+
224+
/**
225+
* An array of a growing tagged union that drops members this build does not
226+
* know. Known members decode through their own schema and still fail when
227+
* broken. Encoding is the plain array encoding.
228+
*/
229+
export const ForwardCompatibleUnionArray = <
230+
const Members extends ReadonlyArray<Schema.Top & { readonly fields: object }>,
231+
const Tag extends string,
232+
>(
233+
members: Members,
234+
tag: Tag,
235+
) =>
236+
Schema.Array(ForwardCompatibleUnion(members, tag)).pipe(
113237
Schema.decodeTo(
114-
Schema.Array(element),
115-
SchemaTransformation.transform<ReadonlyArray<Element["Encoded"]>, ReadonlyArray<unknown>>({
238+
Schema.Array(Schema.toType(Schema.Union(members))),
239+
SchemaTransformation.transform<
240+
ReadonlyArray<Members[number]["Type"]>,
241+
ReadonlyArray<Members[number]["Type"] | UnknownUnionMember<Tag>>
242+
>({
116243
decode: (values) =>
117-
values.filter((value) => Option.isSome(decodeElement(value))) as ReadonlyArray<
118-
Element["Encoded"]
244+
values.filter((value) => !isUnknownUnionMember(value)) as ReadonlyArray<
245+
Members[number]["Type"]
119246
>,
120247
encode: (values) => values,
121248
}),
122249
),
123250
);
251+
252+
const knownTags = (
253+
members: ReadonlyArray<Schema.Top & { readonly fields: object }>,
254+
tag: string,
255+
): ReadonlySet<string> => {
256+
const tags = new Set<string>();
257+
for (const member of members) {
258+
const field = (member.fields as Record<string, unknown>)[tag] as
259+
| { readonly literal?: unknown; readonly literals?: ReadonlyArray<unknown> }
260+
| undefined;
261+
for (const literal of field?.literals ?? [field?.literal]) {
262+
if (typeof literal !== "string") {
263+
throw new Error(`Every ForwardCompatibleUnion member needs a string literal ${tag}.`);
264+
}
265+
tags.add(literal);
266+
}
267+
}
268+
return tags;
124269
};
125270

126271
/**

0 commit comments

Comments
 (0)