Repository navigation
Expand file tree
/
Copy pathpackages-write-envelope.test.ts
More file actions
295 lines (261 loc) · 13.2 KB
/
Copy pathpackages-write-envelope.test.ts
File metadata and controls
295 lines (261 loc) · 13.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
/**
* [#12034 — shipping half] `client.packages.install` / `enable` / `disable`
* answer the BARE `InstalledPackage` row, and the `{ package; message? }`
* envelope they used to declare is emitted by nothing.
*
* ## What was wrong
*
* These three declared `{ package: any; message?: string }`. That is not an
* ERASED type — it is a FALSE one: no surface has ever sent that body. Because
* the member was `any`,
*
* (await client.packages.enable(id)).package
*
* compiled, and was `undefined` at runtime. The `any` is precisely what kept
* the falsehood invisible; a bound-but-wrong declaration is the shape an AI
* consumer reads as ground truth and writes against.
*
* ## Why there was no "which surface do we match" question
*
* `GET /packages/:id` genuinely forks between the two mounted surfaces, which
* is why its declaration is untouched (see `index.ts`, and the cost analysis on
* #12034). These three do not fork, because the REST registrar mounts no twin
* for any of them — MEASURED by driving `registerPackageRoutes` and
* enumerating what came back:
*
* ["POST /api/v1/packages/publish", "GET /api/v1/packages",
* "GET /api/v1/packages/:id", "DELETE /api/v1/packages/:id"]
*
* `POST /packages`, `PATCH /packages/:id/enable` and
* `PATCH /packages/:id/disable` are absent. One producer, therefore one true
* type, therefore nothing to choose between.
*
* ## Why this file is a WIRE test and not a type test
*
* The two halves are separate on purpose and neither substitutes for the other
* (`return-type-precision.test.ts` states the rule in its header):
*
* - a runtime test cannot observe a return-type narrowing at all — the value
* is identical whatever the declaration says. The DECLARATION half is
* pinned type-level in `return-type-precision.test.ts`.
* - a type test cannot observe whether the declaration is TRUE. That is this
* file's job, and it is why nothing here mocks a response body: a mock body
* would assert my own assumption about the producer, which is exactly the
* mistake that produced the false declaration in the first place.
*
* So the chain below is real end to end — a real `SchemaRegistry` from
* `@objectstack/objectql`, the real `HttpDispatcher` from `@objectstack/runtime`
* answering it, and the real `ObjectStackClient` (real `unwrapResponse`)
* reading the result. The only stand-in is the socket: `fetch` hands the
* request to the dispatcher in-process instead of over TCP, and hands back the
* dispatcher's own body untouched.
*
* ---------------------------------------------------------------------------
* Reverse verification, direction predicted BEFORE running
* ---------------------------------------------------------------------------
* Restoring `{ package: any; message?: string }` on the three methods leaves
* THIS file green — the wire value does not change — and turns
* `return-type-precision.test.ts` RED under `tsc`. That asymmetry is the whole
* reason both files exist; the ablation is recorded on the PR against the type
* half, which is the half a declaration change can move.
*/
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import { mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { SchemaRegistry } from '@objectstack/objectql';
import { HttpDispatcher } from '@objectstack/runtime';
// The route map ships from `/api-assembled` (its read responses embed the
// assembled package body); the install output it binds is declared in `/api`.
import { PackageApiContracts } from '@objectstack/spec/api-assembled';
import { ObjectStackClient } from './index';
const BASE_URL = 'http://localhost:3000';
const PACKAGES_PATH = '/api/v1/packages';
const MANIFEST = {
id: 'com.acme.crm',
name: 'Acme CRM',
version: '1.0.0',
type: 'app',
namespace: 'acme',
} as const;
/**
* The caller the `/packages` domain gates on: ADR-0106 D4 read capabilities for
* the reads, `manage_metadata` for the writes. Anonymous is refused before any
* of this (a separate, already-pinned rule), so the envelope under test is only
* reachable with a resolved principal.
*/
const CONTEXT = (): any => ({
request: {},
environmentId: 'os-12034-envelope',
executionContext: {
userId: 'u_admin',
isSystem: false,
systemPermissions: ['manage_metadata', 'studio.access', 'setup.access'],
},
});
/**
* The in-process socket. Everything either side of it is production code: the
* URL the client built goes in, the body the dispatcher produced comes back,
* and nothing in between rewrites a key.
*/
function dispatcherBackedClient(registry: SchemaRegistry) {
const kernel: any = {
context: { getService: (name: string) => (name === 'objectql' ? { registry } : null) },
};
const dispatcher = new HttpDispatcher(kernel);
const seen: Array<{ method: string; path: string; body: unknown }> = [];
const fetchImpl = async (url: string, init: RequestInit = {}): Promise<any> => {
const parsed = new URL(String(url));
expect(parsed.pathname.startsWith(PACKAGES_PATH)).toBe(true);
const subPath = parsed.pathname.slice(PACKAGES_PATH.length);
const method = init.method ?? 'GET';
const body = init.body ? JSON.parse(String(init.body)) : undefined;
seen.push({ method, path: subPath, body });
const result = await dispatcher.handlePackages(
subPath,
method,
body,
Object.fromEntries(parsed.searchParams),
CONTEXT(),
);
const status = result.response?.status ?? 500;
const payload = result.response?.body;
return {
ok: status >= 200 && status < 300,
status,
statusText: String(status),
headers: new Headers(),
json: async () => payload,
};
};
const client = new ObjectStackClient({ baseUrl: BASE_URL, fetch: fetchImpl as any });
return { client, dispatcher, seen };
}
let osHome: string;
let previousOsHome: string | undefined;
beforeAll(() => {
// `enable` / `disable` persist the operator's choice under OS_HOME. Point
// that at a scratch dir so the suite never writes to a real home.
previousOsHome = process.env.OS_HOME;
osHome = mkdtempSync(join(tmpdir(), 'os-12034-'));
process.env.OS_HOME = osHome;
});
afterAll(() => {
if (previousOsHome === undefined) delete process.env.OS_HOME;
else process.env.OS_HOME = previousOsHome;
rmSync(osHome, { recursive: true, force: true });
});
describe('#12034 — the packages write verbs answer the bare row, not `{ package }`', () => {
it('install resolves to the row itself, and has no `package` member to read', async () => {
const registry = new SchemaRegistry();
const { client, seen } = dispatcherBackedClient(registry);
const installed = await client.packages.install(MANIFEST);
// It reached the route the card is about.
expect(seen).toEqual([{ method: 'POST', path: '', body: { manifest: MANIFEST } }]);
// THE LINE THAT WAS A LIE: the declaration promised `.package`.
expect((installed as any).package).toBeUndefined();
expect((installed as any).message).toBeUndefined();
// What actually comes back is the row — identical to what the registry
// holds, which is the value the new declaration names.
expect(installed.manifest).toEqual(MANIFEST);
expect(installed).toEqual(registry.getPackage(MANIFEST.id));
});
it('enable resolves to the row, carrying the flag it just set', async () => {
const registry = new SchemaRegistry();
registry.installPackage(MANIFEST as any, 'authored');
registry.disablePackage(MANIFEST.id);
const { client, seen } = dispatcherBackedClient(registry);
const row = await client.packages.enable(MANIFEST.id);
expect(seen).toEqual([{ method: 'PATCH', path: '/com.acme.crm/enable', body: undefined }]);
expect((row as any).package).toBeUndefined();
expect((row as any).message).toBeUndefined();
// The state the verb changed is read OFF THE ROW — the read the old
// declaration sent callers looking for under `.package`.
expect(row.enabled).toBe(true);
expect(row).toEqual(registry.getPackage(MANIFEST.id));
});
it('disable resolves to the row, carrying the flag it just cleared', async () => {
const registry = new SchemaRegistry();
registry.installPackage(MANIFEST as any, 'authored');
const { client, seen } = dispatcherBackedClient(registry);
const row = await client.packages.disable(MANIFEST.id);
expect(seen).toEqual([{ method: 'PATCH', path: '/com.acme.crm/disable', body: undefined }]);
expect((row as any).package).toBeUndefined();
expect((row as any).message).toBeUndefined();
expect(row.enabled).toBe(false);
expect(row).toEqual(registry.getPackage(MANIFEST.id));
});
/**
* The premise the three assertions above rest on. `unwrapResponse` strips
* exactly ONE `{ success, data }` envelope, so "the dispatcher sends
* `success(pkg)`" and "the caller receives `pkg`" are the same statement
* only while that stays true. Pinned here against the REAL dispatcher body
* rather than a written-out literal.
*/
it('the dispatcher wraps the row exactly once, and the client strips exactly that', async () => {
const registry = new SchemaRegistry();
registry.installPackage(MANIFEST as any, 'authored');
const { client, dispatcher } = dispatcherBackedClient(registry);
const raw = await dispatcher.handlePackages('/com.acme.crm/enable', 'PATCH', undefined, {}, CONTEXT());
const body: any = raw.response?.body;
// The producer's own body: one envelope, the row under `data`, and no
// `package` key anywhere in it.
expect(Object.keys(body).sort()).toEqual(['data', 'meta', 'success']);
expect(body.success).toBe(true);
expect('package' in body.data).toBe(false);
// …and the post-unwrap value the SDK hands the caller is that `data`.
expect(await client.packages.enable(MANIFEST.id)).toEqual(body.data);
});
});
/**
* [#30464] The published contract for `POST /api/v1/packages`, held against
* what the door really answers.
*
* The half above pins the CLIENT's declaration to the wire. This half pins the
* SPEC's: `PackageApiContracts.installPackage.output` is what an integrator
* generates a client from, and it declared `data: { package, … }` — a wrapper
* no surface sends, so code written against it read `data.package` and got
* `undefined`. The contract now follows the wire (the door was not changed).
*
* Same in-process chain as above: a real `SchemaRegistry`, the real
* `HttpDispatcher` answering it, and the dispatcher's own body handed to the
* declared schema untouched. Nothing here writes the expected body out by
* hand, which is how the false declaration survived in the first place.
*/
describe('#30464 — PackageApiContracts.installPackage.output parses the install door\'s real answer', () => {
async function installThroughTheDoor() {
const registry = new SchemaRegistry();
const { dispatcher } = dispatcherBackedClient(registry);
const raw = await dispatcher.handlePackages('', 'POST', { manifest: MANIFEST }, {}, CONTEXT());
return { registry, status: raw.response?.status, body: raw.response?.body as any };
}
it('the door\'s 201 body parses green, and the parse keeps every key the door sent', async () => {
const { registry, status, body } = await installThroughTheDoor();
expect(status).toBe(201);
const parsed = PackageApiContracts.installPackage.output.safeParse(body);
expect(parsed.success, JSON.stringify(parsed.error?.issues)).toBe(true);
// The declared `data` IS the row the registry recorded, and no key the
// door sent is stripped by the parse. (`toMatchObject`, not `toEqual`:
// the parsed value also carries the manifest defaults the declaration
// applies — `scope`, `defaultDatasource` — which is the ADR-0122
// `Parsed` shape, not a residue.)
expect(body.data).toEqual(registry.getPackage(MANIFEST.id));
expect(parsed.data!.data).toMatchObject(body.data);
expect(parsed.data!.data.manifest.id).toBe(MANIFEST.id);
});
it('the old `{ package }` reading is refused by the contract, and absent from the wire', async () => {
const { body } = await installThroughTheDoor();
expect('package' in body.data).toBe(false);
expect('message' in body.data).toBe(false);
// The wrapper the contract used to promise, built from the door's own
// row, no longer passes it: the declaration and the wire cannot both
// be read as true.
const wrapped = { ...body, data: { package: body.data } };
const parsed = PackageApiContracts.installPackage.output.safeParse(wrapped);
expect(parsed.success).toBe(false);
expect(parsed.error!.issues.map((i) => i.path.join('.'))).toEqual(
expect.arrayContaining(['data.manifest', 'data.source']),
);
});
});