@crombolo/extension 0.0.0-stage → 0.57.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kineco
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/NOTICE ADDED
@@ -0,0 +1,78 @@
1
+ crombolo
2
+ Copyright (c) 2026 Kineco
3
+
4
+ This product includes third-party software. crombolo is an independent project.
5
+ It is not affiliated with, endorsed by, or sponsored by Umbraco A/S, which owns
6
+ the Umbraco trademark.
7
+
8
+ There are three places third-party material is redistributed, rather than merely
9
+ depended on:
10
+
11
+ @crombolo/backoffice-dist the built Umbraco backoffice and the browser
12
+ packages bundled into it, produced by
13
+ `bun run vendor:backoffice`
14
+ @crombolo/backoffice-dist three CSS files copied unmodified from the Umbraco
15
+ client source tree
16
+ @crombolo/contracts the Umbraco Management API OpenAPI document,
17
+ copied unmodified
18
+
19
+ No Umbraco trademark is redistributed. The Umbraco wordmark, the "U" roundel
20
+ favicon and the installer illustration are deliberately not carried in this
21
+ repository: MIT grants copyright permission and says nothing about trademarks, so
22
+ crombolo's own marks are served at those paths instead. See `BRANDED_ASSETS` in
23
+ `@crombolo/backoffice-host`.
24
+
25
+ The Umbraco backoffice
26
+ ----------------------
27
+ @umbraco-cms/backoffice 18.2.0 — MIT — https://github.com/umbraco/Umbraco-CMS
28
+ @umbraco-ui/uui 2.0.2 — MIT — https://github.com/umbraco/Umbraco.UI
29
+
30
+ The Lato fonts
31
+ -------------
32
+ LatoLatin-*.woff2 — Copyright (c) 2011-2015 by tyPoland Lukasz Dziedzic, with
33
+ Reserved Font Name "Lato" — SIL Open Font License 1.1 — https://www.latofonts.com
34
+ Shipped unmodified, as @umbraco-ui/uui ships them, in @crombolo/backoffice-dist
35
+ under `dist/assets/fonts/`, with the licence beside them as `OFL.txt`
36
+ (`packages/backoffice-dist/licenses/Lato-OFL.txt` in this repository). The
37
+ fonts carry the same notice in their own metadata.
38
+
39
+ Static files from the Umbraco client source tree
40
+ ------------------------------------------------
41
+ css/umb-css.css, css/rte-content.css, css/umbraco-blockgridlayout.css
42
+ — copied unmodified from Umbraco-CMS release-18.2.0 — MIT
43
+ — https://github.com/umbraco/Umbraco-CMS
44
+ Shipped in @crombolo/backoffice-dist under `upstream-static/`.
45
+
46
+ `rte-content.css` itself carries Tiptap's default editor styles, copied from
47
+ tiptap v2.11.7 (MIT); the file records this in its own header.
48
+
49
+ The Umbraco Management API contract
50
+ -----------------------------------
51
+ OpenApi.json — copied unmodified from Umbraco-CMS release-18.2.0
52
+ (src/Umbraco.Cms.Api.Management/OpenApi.json) — MIT
53
+ — https://github.com/umbraco/Umbraco-CMS
54
+ Shipped in @crombolo/contracts, which also ships the TypeScript types generated
55
+ from it.
56
+
57
+ Browser runtime dependencies bundled into the backoffice build
58
+ --------------------------------------------------------------
59
+ @heximal/expressions 0.1.5 — BSD-3-Clause
60
+ @microsoft/signalr 10.0.11 — MIT
61
+ @tiptap/* 3.31.3 — MIT
62
+ diff 9.0.0 — BSD-3-Clause
63
+ dompurify 3.4.16 — Apache-2.0, elected from "MPL-2.0 OR Apache-2.0"
64
+ element-internals-polyfill 3.0.2 — MIT
65
+ lit 3.3.3 — BSD-3-Clause
66
+ luxon 3.7.2 — MIT
67
+ marked 18.0.14 — MIT
68
+ monaco-editor 0.57.0 — MIT
69
+ rxjs 7.8.2 — Apache-2.0
70
+ uuid 14.0.2 — MIT
71
+
72
+ dompurify is offered under either licence; Apache-2.0 is elected here, so no
73
+ MPL-2.0 obligation attaches to the copy bundled into the backoffice build. Of the
74
+ Apache-2.0 packages above, none ships a NOTICE file of its own, so Apache-2.0
75
+ section 4(d) adds nothing to this file.
76
+
77
+ Each package's own licence text ships inside its npm distribution and applies
78
+ unchanged to the copies bundled here.
package/package.json CHANGED
@@ -1,6 +1,44 @@
1
1
  {
2
2
  "name": "@crombolo/extension",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.57.0",
4
+ "description": "What an extension's server half is written against: route, the host's capabilities and its own tables. It runs in a Deno process of its own, apart from the CMS.",
5
+ "license": "MIT",
6
+ "author": "Crombolo",
7
+ "homepage": "https://github.com/kineco-au/crombolo-cms#readme",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/kineco-au/crombolo-cms.git",
11
+ "directory": "packages/extension"
12
+ },
13
+ "bugs": {
14
+ "url": "https://github.com/kineco-au/crombolo-cms/issues"
15
+ },
16
+ "keywords": [
17
+ "crombolo",
18
+ "extension",
19
+ "deno"
20
+ ],
21
+ "engines": {
22
+ "bun": ">=1.3.0"
23
+ },
24
+ "type": "module",
25
+ "exports": {
26
+ ".": "./src/index.ts",
27
+ "./channel": "./src/channel.ts",
28
+ "./runner": "./src/runner.ts"
29
+ },
30
+ "files": [
31
+ "src",
32
+ "NOTICE"
33
+ ],
34
+ "dependencies": {
35
+ "@crombolo/common": "0.57.0",
36
+ "@crombolo/core": "0.57.0",
37
+ "@crombolo/data": "0.57.0",
38
+ "@crombolo/render": "0.57.0",
39
+ "kysely": "0.29.6"
40
+ },
41
+ "publishConfig": {
42
+ "access": "public"
43
+ }
44
+ }
package/src/channel.ts ADDED
@@ -0,0 +1,329 @@
1
+ /**
2
+ * The channel between the CMS and an extension's process (story 311): frames of
3
+ * JSON, each prefixed with its length, over the process's standard input and
4
+ * output. Runs on Bun and Deno alike, so both ends share it.
5
+ *
6
+ * Values that JSON cannot carry are tagged: dates, bytes, maps, errors,
7
+ * responses and the `Result` a route may answer with. docs/extensions.md, "The
8
+ * channel".
9
+ */
10
+ import { Ok, Outcome } from '@crombolo/common'
11
+
12
+ /** The largest frame either end accepts: a body travels in chunks well below it. */
13
+ export const MAX_FRAME_BYTES = 16 * 1024 * 1024
14
+
15
+ /** The size of each chunk a body is streamed in. */
16
+ export const CHUNK_BYTES = 64 * 1024
17
+
18
+ export type Frame = Record<string, unknown> & { t: string }
19
+
20
+ const encoder = new TextEncoder()
21
+ const decoder = new TextDecoder()
22
+
23
+ /** One frame as bytes: its length, big-endian, then its JSON. */
24
+ export function frameBytes(frame: Frame): Uint8Array {
25
+ const body = encoder.encode(JSON.stringify(frame))
26
+ if (body.length > MAX_FRAME_BYTES)
27
+ throw new Error(`A frame of ${body.length} bytes is past the ${MAX_FRAME_BYTES} allowed.`)
28
+ const out = new Uint8Array(4 + body.length)
29
+ new DataView(out.buffer).setUint32(0, body.length)
30
+ out.set(body, 4)
31
+ return out
32
+ }
33
+
34
+ /** Reads frames from a byte stream as they complete; ends when the stream does. */
35
+ export async function* readFrames(stream: ReadableStream<Uint8Array>): AsyncGenerator<Frame> {
36
+ const reader = stream.getReader()
37
+ let buffer = new Uint8Array(0)
38
+ for (;;) {
39
+ while (buffer.length >= 4) {
40
+ const length = new DataView(buffer.buffer, buffer.byteOffset).getUint32(0)
41
+ if (length > MAX_FRAME_BYTES)
42
+ throw new Error(`A frame of ${length} bytes is past the ${MAX_FRAME_BYTES} allowed.`)
43
+ if (buffer.length < 4 + length) break
44
+ const frame = JSON.parse(decoder.decode(buffer.subarray(4, 4 + length))) as Frame
45
+ buffer = buffer.slice(4 + length)
46
+ yield frame
47
+ }
48
+ const { value, done } = await reader.read()
49
+ if (done) return
50
+ const joined = new Uint8Array(buffer.length + value.length)
51
+ joined.set(buffer)
52
+ joined.set(value, buffer.length)
53
+ buffer = joined
54
+ }
55
+ }
56
+
57
+ export function toBase64(bytes: Uint8Array): string {
58
+ let text = ''
59
+ for (let i = 0; i < bytes.length; i += 0x8000)
60
+ text += String.fromCharCode(...bytes.subarray(i, i + 0x8000))
61
+ return btoa(text)
62
+ }
63
+
64
+ export function fromBase64(text: string): Uint8Array {
65
+ const raw = atob(text)
66
+ const bytes = new Uint8Array(raw.length)
67
+ for (let i = 0; i < raw.length; i++) bytes[i] = raw.charCodeAt(i)
68
+ return bytes
69
+ }
70
+
71
+ /** A function the other end may call, by its number in the call's table. */
72
+ export interface FnMarker {
73
+ $fn: number
74
+ }
75
+
76
+ /** What `encode` hands back for the parts it cannot carry itself. */
77
+ export interface EncodeHooks {
78
+ /** A function: its number, so the other end can call it. Absent, functions are dropped. */
79
+ fn?(fn: (...args: unknown[]) => unknown): number
80
+ /** An abort signal: its number, so the other end is told when it aborts. */
81
+ signal?(signal: AbortSignal): number
82
+ /** A value this end handles itself, such as an extension's database; undefined to carry on. */
83
+ special?(value: unknown, key: string | undefined): unknown
84
+ /**
85
+ * An object lent by reference: its number, so when the other end passes it
86
+ * back (a page to `nav.children`) this end gets the object itself.
87
+ */
88
+ ref?(value: object): number
89
+ /** More to send with an object that is not plain, such as a page's values (story 312). */
90
+ extra?(value: object): Record<string, unknown> | undefined
91
+ }
92
+
93
+ /** Where a decoded object keeps the number of the object it stands for at the other end. */
94
+ export const REF = Symbol.for('crombolo.channel.ref')
95
+
96
+ const isPlain = (value: object): boolean => {
97
+ const proto = Object.getPrototypeOf(value)
98
+ return proto === Object.prototype || proto === null
99
+ }
100
+
101
+ /**
102
+ * A value as the channel carries it. Async, because a response's or a file's
103
+ * body has to be read. Objects that are not plain keep their data and, with
104
+ * `hooks.fn`, their methods, own or inherited, never `Object`'s.
105
+ */
106
+ export async function encode(
107
+ value: unknown,
108
+ hooks: EncodeHooks = {},
109
+ key?: string,
110
+ seen = new Set<object>(),
111
+ ): Promise<unknown> {
112
+ const special = hooks.special?.(value, key)
113
+ if (special !== undefined) return special
114
+ if (value === null || typeof value !== 'object') {
115
+ if (typeof value === 'function') return hooks.fn ? { $fn: hooks.fn(value as never) } : undefined
116
+ if (typeof value === 'bigint') return { $big: value.toString() }
117
+ if (typeof value === 'number' && !Number.isFinite(value)) return { $num: String(value) }
118
+ return value
119
+ }
120
+ // One the other end lent goes back as its number, and arrives as itself.
121
+ const lent = (value as { [REF]?: number })[REF]
122
+ if (typeof lent === 'number') return { $ref: lent }
123
+ if (typeof (value as { then?: unknown }).then === 'function')
124
+ return encode(await (value as PromiseLike<unknown>), hooks, key, seen)
125
+ if (seen.has(value)) return undefined
126
+ seen.add(value)
127
+ try {
128
+ if (value instanceof Date) return { $date: value.toISOString() }
129
+ if (value instanceof URL) return { $url: value.href }
130
+ if (value instanceof Uint8Array) return { $bytes: toBase64(value) }
131
+ if (value instanceof ArrayBuffer) return { $bytes: toBase64(new Uint8Array(value)) }
132
+ if (ArrayBuffer.isView(value))
133
+ return {
134
+ $bytes: toBase64(new Uint8Array(value.buffer, value.byteOffset, value.byteLength)),
135
+ }
136
+ if (typeof AbortSignal !== 'undefined' && value instanceof AbortSignal)
137
+ return hooks.signal ? { $signal: hooks.signal(value), aborted: value.aborted } : undefined
138
+ if (value instanceof Response)
139
+ return {
140
+ $response: {
141
+ status: value.status,
142
+ statusText: value.statusText,
143
+ headers: [...value.headers],
144
+ body: toBase64(new Uint8Array(await value.arrayBuffer())),
145
+ },
146
+ }
147
+ if (value instanceof Request)
148
+ return {
149
+ $request: {
150
+ url: value.url,
151
+ method: value.method,
152
+ headers: [...value.headers],
153
+ body:
154
+ value.method === 'GET' || value.method === 'HEAD'
155
+ ? null
156
+ : toBase64(new Uint8Array(await value.arrayBuffer())),
157
+ },
158
+ }
159
+ if (typeof Blob !== 'undefined' && value instanceof Blob)
160
+ return {
161
+ $blob: {
162
+ type: value.type,
163
+ name: (value as Blob & { name?: string }).name,
164
+ body: toBase64(new Uint8Array(await value.arrayBuffer())),
165
+ },
166
+ }
167
+ if (value instanceof Map)
168
+ return {
169
+ $map: await Promise.all(
170
+ [...value].map(async ([k, v]) => [
171
+ await encode(k, hooks, undefined, seen),
172
+ await encode(v, hooks, undefined, seen),
173
+ ]),
174
+ ),
175
+ }
176
+ if (value instanceof Set)
177
+ return { $set: await Promise.all([...value].map((v) => encode(v, hooks, undefined, seen))) }
178
+ if (value instanceof Error) return { $error: { name: value.name, message: value.message } }
179
+ if (value instanceof Outcome)
180
+ return {
181
+ $outcome: {
182
+ status: value.status,
183
+ message: value.message,
184
+ errors: value.errors,
185
+ location: value.location,
186
+ },
187
+ }
188
+ if (value instanceof Ok) return { $ok: await encode(value.value, hooks, undefined, seen) }
189
+ if (Array.isArray(value))
190
+ return Promise.all(value.map((v) => encode(v, hooks, undefined, seen)))
191
+ const out: Record<string, unknown> = {}
192
+ if (hooks.ref && hooks.fn && !isPlain(value)) out.$ref = hooks.ref(value)
193
+ const extra = isPlain(value) ? undefined : hooks.extra?.(value)
194
+ for (const [k, v] of Object.entries(extra ?? {})) {
195
+ const encoded = await encode(v, hooks, k, seen)
196
+ if (encoded !== undefined) out[k] = encoded
197
+ }
198
+ for (const [k, v] of Object.entries(value)) {
199
+ if (k.startsWith('$')) continue
200
+ const encoded = await encode(v, hooks, k, seen)
201
+ if (encoded !== undefined) out[k] = encoded
202
+ }
203
+ // A capability built as a class keeps its methods: walked up to, never into, Object's.
204
+ if (hooks.fn && !isPlain(value))
205
+ for (
206
+ let proto = Object.getPrototypeOf(value);
207
+ proto && proto !== Object.prototype;
208
+ proto = Object.getPrototypeOf(proto)
209
+ )
210
+ for (const name of Object.getOwnPropertyNames(proto)) {
211
+ if (name === 'constructor' || name in out) continue
212
+ const descriptor = Object.getOwnPropertyDescriptor(proto, name)
213
+ // A getter's value travels as data: `isVisible`, `culture`.
214
+ if (descriptor?.get) {
215
+ const got = await encode((value as Record<string, unknown>)[name], hooks, name, seen)
216
+ if (got !== undefined) out[name] = got
217
+ continue
218
+ }
219
+ if (typeof descriptor?.value !== 'function') continue
220
+ // Read through the object, so a capability wrapped to check its grant stays wrapped.
221
+ const method = (value as Record<string, unknown>)[name]
222
+ if (typeof method === 'function') out[name] = { $fn: hooks.fn(method.bind(value)) }
223
+ }
224
+ return out
225
+ } finally {
226
+ seen.delete(value)
227
+ }
228
+ }
229
+
230
+ /** What `decode` asks this end to make of the markers the other end sent. */
231
+ export interface DecodeHooks {
232
+ fn?(marker: number): (...args: unknown[]) => unknown
233
+ signal?(marker: number, aborted: boolean): AbortSignal
234
+ /** A tagged value this end owns, such as `$database` or `$incoming`; undefined to carry on. */
235
+ special?(value: Record<string, unknown>): unknown
236
+ /** The object this end lent under a number, when it comes back. */
237
+ ref?(marker: number): unknown
238
+ }
239
+
240
+ /** A value from the channel, with its tags made real again. */
241
+ export function decode(value: unknown, hooks: DecodeHooks = {}): unknown {
242
+ if (value === null || typeof value !== 'object') return value
243
+ if (Array.isArray(value)) return value.map((v) => decode(v, hooks))
244
+ const tagged = value as Record<string, unknown>
245
+ const special = hooks.special?.(tagged)
246
+ if (special !== undefined) return special
247
+ if ('$fn' in tagged) return hooks.fn?.(tagged.$fn as number)
248
+ if ('$signal' in tagged)
249
+ return (
250
+ hooks.signal?.(tagged.$signal as number, tagged.aborted === true) ??
251
+ new AbortController().signal
252
+ )
253
+ if ('$date' in tagged) return new Date(tagged.$date as string)
254
+ if ('$url' in tagged) return new URL(tagged.$url as string)
255
+ if ('$bytes' in tagged) return fromBase64(tagged.$bytes as string)
256
+ if ('$big' in tagged) return BigInt(tagged.$big as string)
257
+ if ('$num' in tagged) return Number(tagged.$num)
258
+ if ('$map' in tagged)
259
+ return new Map(
260
+ (tagged.$map as [unknown, unknown][]).map(([k, v]) => [decode(k, hooks), decode(v, hooks)]),
261
+ )
262
+ if ('$set' in tagged) return new Set((tagged.$set as unknown[]).map((v) => decode(v, hooks)))
263
+ if ('$error' in tagged) return errorFrom(tagged.$error as { name: string; message: string })
264
+ if ('$outcome' in tagged) {
265
+ const o = tagged.$outcome as {
266
+ status: number
267
+ message?: string
268
+ errors?: { field: string; message: string }[]
269
+ location?: string
270
+ }
271
+ return Outcome.of(o.status as never, {
272
+ message: o.message,
273
+ errors: o.errors,
274
+ location: o.location,
275
+ })
276
+ }
277
+ if ('$ok' in tagged) return new Ok(decode(tagged.$ok, hooks))
278
+ if ('$response' in tagged) {
279
+ const r = tagged.$response as {
280
+ status: number
281
+ statusText: string
282
+ headers: [string, string][]
283
+ body: string
284
+ }
285
+ const empty = r.status === 204 || r.status === 304 || (r.status >= 100 && r.status < 200)
286
+ return new Response(empty ? null : (fromBase64(r.body) as BodyInit), {
287
+ status: r.status,
288
+ statusText: r.statusText,
289
+ headers: r.headers,
290
+ })
291
+ }
292
+ if ('$request' in tagged) {
293
+ const r = tagged.$request as {
294
+ url: string
295
+ method: string
296
+ headers: [string, string][]
297
+ body: string | null
298
+ }
299
+ return new Request(r.url, {
300
+ method: r.method,
301
+ headers: r.headers,
302
+ body: r.body === null ? undefined : (fromBase64(r.body) as BodyInit),
303
+ })
304
+ }
305
+ if ('$blob' in tagged) {
306
+ const b = tagged.$blob as { type: string; name?: string; body: string }
307
+ const bytes = fromBase64(b.body) as BlobPart
308
+ return b.name !== undefined
309
+ ? new File([bytes], b.name, { type: b.type })
310
+ : new Blob([bytes], { type: b.type })
311
+ }
312
+ if ('$ref' in tagged && Object.keys(tagged).length === 1)
313
+ return hooks.ref?.(tagged.$ref as number)
314
+ const out: Record<string, unknown> = {}
315
+ for (const [k, v] of Object.entries(tagged)) {
316
+ if (k === '$ref') continue
317
+ out[k] = decode(v, hooks)
318
+ }
319
+ if (typeof tagged.$ref === 'number')
320
+ Object.defineProperty(out, REF, { value: tagged.$ref, enumerable: false })
321
+ return out
322
+ }
323
+
324
+ /** An error from the other end, its name kept so a caller can tell a refusal apart. */
325
+ export function errorFrom(error: { name: string; message: string }): Error {
326
+ const made = new Error(error.message)
327
+ made.name = error.name
328
+ return made
329
+ }
package/src/index.ts ADDED
@@ -0,0 +1,38 @@
1
+ /**
2
+ * What an extension's server half is written against (story 311). The CMS
3
+ * bundles the extension with this package and runs it in a Deno process of its
4
+ * own, so nothing here reaches the CMS except through the channel: routes,
5
+ * events, jobs and workflows arrive as messages, and each capability call goes
6
+ * back to the host, which checks it against the extension's grant.
7
+ *
8
+ * The API is `@crombolo/crombolo/bundle`'s, which an extension may still import:
9
+ * the build points that name here. docs/extensions.md.
10
+ */
11
+ import { sectionKey } from '@crombolo/core/sections'
12
+ import type { BundleStep, BundleTables, ShapeOf } from './types.ts'
13
+
14
+ export * from '@crombolo/common'
15
+ export type * from './types.ts'
16
+
17
+ /** Declares the extension's own tables, built when the CMS starts it. */
18
+ export function defineBundleTables<const Steps extends readonly BundleStep[]>(
19
+ id: string,
20
+ steps: Steps,
21
+ ): BundleTables<ShapeOf<Steps>> {
22
+ return Object.freeze({ id, steps: Object.freeze([...steps]) }) as BundleTables<ShapeOf<Steps>>
23
+ }
24
+
25
+ /** Whether a back-office caller holds a section, named in either vocabulary. */
26
+ export function hasSection(principal: { allowedSections: readonly string[] }, section: string) {
27
+ return principal.allowedSections.some((held) => sectionKey(held) === sectionKey(section))
28
+ }
29
+
30
+ /** Whether a back-office caller may work in every culture named. */
31
+ export function hasCultureAccess(
32
+ principal: { hasAccessToAllLanguages: boolean; languages: readonly string[] },
33
+ cultures: readonly string[],
34
+ ): boolean {
35
+ if (principal.hasAccessToAllLanguages) return true
36
+ const allowed = new Set(principal.languages.map((l) => l.toLowerCase()))
37
+ return cultures.every((c) => allowed.has(c.toLowerCase()))
38
+ }
package/src/runner.ts ADDED
@@ -0,0 +1,487 @@
1
+ /**
2
+ * The extension's end of the channel (story 311), run under Deno. The CMS
3
+ * builds an entry that imports the extension and calls `run` with it: this
4
+ * builds the extension from its factory, describes it to the CMS, then answers
5
+ * routes, events, jobs, workflows and backfills as the CMS sends them.
6
+ *
7
+ * Everything the extension does to the site goes back over the channel: each
8
+ * capability is a function the CMS lent for this one call, and its tables are a
9
+ * Kysely whose queries the CMS runs on the connection that reaches only them.
10
+ * docs/extensions.md, "The channel".
11
+ */
12
+ import { schemaBuilder } from '@crombolo/data/tables-builder'
13
+ import { RawHtml } from '@crombolo/render/html'
14
+ import { type Child, renderToString } from '@crombolo/render/jsx-runtime'
15
+ import {
16
+ type CompiledQuery,
17
+ type DatabaseConnection,
18
+ type Driver,
19
+ Kysely,
20
+ PostgresAdapter,
21
+ PostgresIntrospector,
22
+ PostgresQueryCompiler,
23
+ type QueryResult,
24
+ SqliteAdapter,
25
+ SqliteIntrospector,
26
+ SqliteQueryCompiler,
27
+ } from 'kysely'
28
+ import {
29
+ CHUNK_BYTES,
30
+ decode,
31
+ encode,
32
+ errorFrom,
33
+ type Frame,
34
+ frameBytes,
35
+ fromBase64,
36
+ readFrames,
37
+ toBase64,
38
+ } from './channel.ts'
39
+
40
+ declare const Deno: {
41
+ stdin: { readable: ReadableStream<Uint8Array> }
42
+ stdout: { writable: WritableStream<Uint8Array> }
43
+ exit(code: number): never
44
+ }
45
+
46
+ // biome-ignore lint/suspicious/noExplicitAny: an extension's bundle is untyped here
47
+ type Bundle = Record<string, any>
48
+
49
+ /** What the CMS learns of the extension at start, to mount it. */
50
+ export interface ExtensionDescription {
51
+ id: string
52
+ section: string
53
+ capabilities: string[]
54
+ routes: { index: number; path: string; options: Record<string, unknown>; methods: string[] }[]
55
+ tables?: {
56
+ id: string
57
+ steps: {
58
+ name: string
59
+ release: string
60
+ ops: unknown[]
61
+ backfill: boolean
62
+ sql: boolean
63
+ }[]
64
+ }
65
+ media?: unknown
66
+ events: string[]
67
+ jobs: string[]
68
+ schedules?: unknown
69
+ workflows: { type: string; label: string; settings?: unknown }[]
70
+ fields: number
71
+ middleware: boolean
72
+ /** Its components (story 312), each with the layout alias it suggests. */
73
+ components: { name: string; layout?: string }[]
74
+ }
75
+
76
+ /** A component as the factory declares it: its render function, or its module. */
77
+ type DeclaredComponent =
78
+ | ((props: object) => unknown)
79
+ | { default: (props: object) => unknown; layout?: string }
80
+
81
+ const renderOf = (component: DeclaredComponent | undefined) =>
82
+ typeof component === 'function'
83
+ ? component
84
+ : typeof component?.default === 'function'
85
+ ? component.default
86
+ : undefined
87
+
88
+ function describe(bundle: Bundle): ExtensionDescription {
89
+ return {
90
+ id: bundle.id,
91
+ section: bundle.section,
92
+ capabilities: [...(bundle.capabilities ?? [])],
93
+ routes: (bundle.routes ?? []).map(
94
+ (
95
+ route: { path: string; options?: Record<string, unknown>; handlers?: object },
96
+ index: number,
97
+ ) => ({
98
+ index,
99
+ path: route?.path,
100
+ options: route?.options ?? {},
101
+ methods: Object.keys(route?.handlers ?? {}),
102
+ }),
103
+ ),
104
+ tables: bundle.tables
105
+ ? {
106
+ id: bundle.tables.id,
107
+ steps: bundle.tables.steps.map((step: Bundle) => ({
108
+ name: step.name,
109
+ release: step.release,
110
+ ops: typeof step.up === 'function' ? [step.up(schemaBuilder)].flat() : [],
111
+ backfill: typeof step.backfill === 'function',
112
+ sql: 'sql' in step,
113
+ })),
114
+ }
115
+ : undefined,
116
+ media: bundle.media,
117
+ events: Object.keys(bundle.events ?? {}),
118
+ jobs: Object.keys(bundle.jobs ?? {}),
119
+ schedules: bundle.schedules,
120
+ workflows: (bundle.forms?.workflows ?? []).map(
121
+ (workflow: { type: string; label: string; settings?: unknown }) => ({
122
+ type: workflow.type,
123
+ label: workflow.label,
124
+ settings: workflow.settings,
125
+ }),
126
+ ),
127
+ fields: (bundle.forms?.fields ?? []).length,
128
+ middleware: bundle.middleware !== undefined,
129
+ components: Object.entries((bundle.components ?? {}) as Record<string, DeclaredComponent>)
130
+ .filter(([, component]) => renderOf(component))
131
+ .map(([name, component]) => ({
132
+ name,
133
+ ...(typeof component === 'object' && typeof component.layout === 'string'
134
+ ? { layout: component.layout }
135
+ : {}),
136
+ })),
137
+ }
138
+ }
139
+
140
+ const hasAny = (value: unknown) =>
141
+ value !== null &&
142
+ value !== undefined &&
143
+ value !== '' &&
144
+ !(Array.isArray(value) && value.length === 0)
145
+
146
+ /**
147
+ * A page or element whose values came with it (story 312): `value()`, `text()`,
148
+ * `html()` and `hasValue()` answer at once, as a site component's do. With
149
+ * options, or for a value that did not come, they ask the CMS.
150
+ */
151
+ function withValues(target: Bundle, values: Record<string, Bundle>): Bundle {
152
+ const live = {
153
+ value: target.value,
154
+ text: target.text,
155
+ html: target.html,
156
+ hasValue: target.hasValue,
157
+ }
158
+ const sent = (alias: string, options: unknown) =>
159
+ options === undefined && Object.hasOwn(values, alias) ? values[alias] : undefined
160
+ target.value = (alias: string, options?: unknown) =>
161
+ sent(alias, options)?.value ?? (sent(alias, options) ? undefined : live.value?.(alias, options))
162
+ target.text = (alias: string, options?: unknown) =>
163
+ sent(alias, options)?.text ?? live.text?.(alias, options)
164
+ target.html = (alias: string, options?: unknown) =>
165
+ sent(alias, options)?.html ?? live.html?.(alias, options)
166
+ target.hasValue = (alias: string, options?: unknown) =>
167
+ sent(alias, options) ? hasAny(sent(alias, options)?.value) : live.hasValue?.(alias, options)
168
+ return target
169
+ }
170
+
171
+ /** Starts the extension's end of the channel: never returns while the CMS keeps it open. */
172
+ export async function run(module: Record<string, unknown>, exportName: string): Promise<void> {
173
+ const writer = Deno.stdout.writable.getWriter()
174
+ let queue: Promise<void> = Promise.resolve()
175
+ const send = (frame: Frame): Promise<void> => {
176
+ queue = queue.then(() => writer.write(frameBytes(frame))).catch(() => {})
177
+ return queue
178
+ }
179
+
180
+ // Standard output is the channel, so the console is sent to the site's log instead.
181
+ const text = (part: unknown) => {
182
+ if (typeof part === 'string') return part
183
+ if (part instanceof Error) return part.stack ?? part.message
184
+ try {
185
+ return JSON.stringify(part)
186
+ } catch {
187
+ return String(part)
188
+ }
189
+ }
190
+ for (const [method, level] of [
191
+ ['log', 'info'],
192
+ ['info', 'info'],
193
+ ['debug', 'debug'],
194
+ ['warn', 'warn'],
195
+ ['error', 'error'],
196
+ ] as const)
197
+ console[method] = (...parts: unknown[]) => {
198
+ send({ t: 'log', level, message: parts.map(text).join(' ') })
199
+ }
200
+ globalThis.addEventListener?.('unhandledrejection', (event: Event) => {
201
+ event.preventDefault()
202
+ const reason = (event as PromiseRejectionEvent).reason
203
+ send({ t: 'log', level: 'error', message: `Unhandled: ${text(reason)}` })
204
+ })
205
+
206
+ let bundle: Bundle | undefined
207
+ let dialect: 'sqlite' | 'postgres' = 'sqlite'
208
+ let nextId = 1
209
+ const pending = new Map<number, { resolve(value: unknown): void; reject(error: Error): void }>()
210
+ const ask = (frame: Frame): Promise<unknown> =>
211
+ new Promise((resolve, reject) => {
212
+ const id = nextId++
213
+ pending.set(id, { resolve, reject })
214
+ send({ ...frame, id })
215
+ })
216
+
217
+ const signals = new Map<number, AbortController>()
218
+ const waiting = new Map<number, { controller: ReadableStreamDefaultController; done(): void }>()
219
+ const incoming = new WeakMap<Request, number>()
220
+ const databases = new Map<string, Kysely<never>>()
221
+
222
+ class ChannelConnection implements DatabaseConnection {
223
+ conn: number | undefined
224
+ constructor(readonly db: string) {}
225
+ async executeQuery<R>(compiled: CompiledQuery): Promise<QueryResult<R>> {
226
+ const value = await ask({
227
+ t: 'sql',
228
+ db: this.db,
229
+ conn: this.conn,
230
+ query: await encode(compiled.query),
231
+ })
232
+ return decode(value) as QueryResult<R>
233
+ }
234
+ // biome-ignore lint/correctness/useYield: streaming is refused before anything is yielded
235
+ async *streamQuery<R>(): AsyncIterableIterator<QueryResult<R>> {
236
+ throw new Error('Streaming a query is not offered to an extension.')
237
+ }
238
+ }
239
+
240
+ class ChannelDriver implements Driver {
241
+ constructor(readonly db: string) {}
242
+ async init() {}
243
+ async acquireConnection() {
244
+ return new ChannelConnection(this.db)
245
+ }
246
+ async beginTransaction(connection: DatabaseConnection) {
247
+ ;(connection as ChannelConnection).conn = (await ask({ t: 'begin', db: this.db })) as number
248
+ }
249
+ async commitTransaction(connection: DatabaseConnection) {
250
+ const c = connection as ChannelConnection
251
+ await ask({ t: 'commit', db: this.db, conn: c.conn })
252
+ c.conn = undefined
253
+ }
254
+ async rollbackTransaction(connection: DatabaseConnection) {
255
+ const c = connection as ChannelConnection
256
+ await ask({ t: 'rollback', db: this.db, conn: c.conn })
257
+ c.conn = undefined
258
+ }
259
+ async releaseConnection() {}
260
+ async destroy() {}
261
+ }
262
+
263
+ const databaseFor = (db: string): Kysely<never> => {
264
+ let found = databases.get(db)
265
+ if (found) return found
266
+ const pg = dialect === 'postgres'
267
+ found = new Kysely<never>({
268
+ dialect: {
269
+ createAdapter: () => (pg ? new PostgresAdapter() : new SqliteAdapter()),
270
+ createDriver: () => new ChannelDriver(db),
271
+ createIntrospector: (k) => (pg ? new PostgresIntrospector(k) : new SqliteIntrospector(k)),
272
+ createQueryCompiler: () => (pg ? new PostgresQueryCompiler() : new SqliteQueryCompiler()),
273
+ },
274
+ })
275
+ databases.set(db, found)
276
+ return found
277
+ }
278
+
279
+ const decodeFor =
280
+ (call: number) =>
281
+ (value: unknown): unknown =>
282
+ decode(value, {
283
+ fn:
284
+ (fn) =>
285
+ (...args: unknown[]) =>
286
+ callHost(call, fn, args),
287
+ signal: (marker, aborted) => {
288
+ let controller = signals.get(marker)
289
+ if (!controller) {
290
+ controller = new AbortController()
291
+ signals.set(marker, controller)
292
+ }
293
+ if (aborted) controller.abort()
294
+ return controller.signal
295
+ },
296
+ special: (tagged): unknown => {
297
+ if ('$database' in tagged) return databaseFor(String(tagged.$database))
298
+ if ('$html' in tagged) return new RawHtml(String(tagged.$html))
299
+ if ('$values' in tagged) {
300
+ const { $values, ...rest } = tagged
301
+ return withValues(
302
+ decodeFor(call)(rest) as Bundle,
303
+ decodeFor(call)($values) as Record<string, Bundle>,
304
+ )
305
+ }
306
+ return undefined
307
+ },
308
+ })
309
+
310
+ async function callHost(call: number, fn: number, args: unknown[]): Promise<unknown> {
311
+ const encoded = await encode(args, {
312
+ // The request a route was given goes back as itself, its body unread.
313
+ special: (value) =>
314
+ value instanceof Request && incoming.has(value) && !value.bodyUsed
315
+ ? { $incoming: incoming.get(value) }
316
+ : undefined,
317
+ })
318
+ return decodeFor(call)(await ask({ t: 'host', call, fn, args: encoded }))
319
+ }
320
+
321
+ function requestFor(
322
+ id: number,
323
+ given: { url: string; method: string; headers: [string, string][]; hasBody: boolean },
324
+ ) {
325
+ const body = given.hasBody
326
+ ? new ReadableStream<Uint8Array>({
327
+ pull: (controller) =>
328
+ new Promise<void>((done) => {
329
+ waiting.set(id, { controller, done })
330
+ send({ t: 'pull', id })
331
+ }),
332
+ })
333
+ : undefined
334
+ const request = new Request(given.url, {
335
+ method: given.method,
336
+ headers: given.headers,
337
+ body,
338
+ ...(body ? { duplex: 'half' } : {}),
339
+ } as RequestInit)
340
+ incoming.set(request, id)
341
+ return request
342
+ }
343
+
344
+ const cookiesFrom = (pairs: [string, string][]) => {
345
+ const all = pairs.map(([name, value]) => ({ name, value }))
346
+ return {
347
+ get: (name: string) => all.find((cookie) => cookie.name === name),
348
+ getAll: (name?: string) => (name ? all.filter((cookie) => cookie.name === name) : [...all]),
349
+ has: (name: string) => all.some((cookie) => cookie.name === name),
350
+ size: all.length,
351
+ [Symbol.iterator]: () =>
352
+ all.map((cookie) => [cookie.name, cookie] as const)[Symbol.iterator](),
353
+ }
354
+ }
355
+
356
+ const noSite = () => {
357
+ throw new Error("An extension cannot use site(): read the site's content through bundle.api.")
358
+ }
359
+
360
+ async function dispatch(frame: Frame): Promise<unknown> {
361
+ if (!bundle) throw new Error('The extension has not started.')
362
+ const id = frame.id as number
363
+ const context = decodeFor(id)(frame.context) as Bundle
364
+ switch (frame.kind) {
365
+ case 'route': {
366
+ const route = bundle.routes?.[frame.route as number]
367
+ const handler = route?.handlers?.[frame.method as string]
368
+ if (typeof handler !== 'function') throw new Error('No such route.')
369
+ context.cookies = cookiesFrom((frame.cookies as [string, string][]) ?? [])
370
+ context.site = noSite
371
+ return handler(requestFor(id, frame.request as never), context)
372
+ }
373
+ case 'event':
374
+ return bundle.events[frame.name as string](context)
375
+ case 'job':
376
+ return bundle.jobs[frame.name as string](context.payload, context.context)
377
+ case 'workflow': {
378
+ const workflow = (bundle.forms?.workflows ?? []).find(
379
+ (candidate: { type: string }) => candidate.type === frame.name,
380
+ )
381
+ if (!workflow) throw new Error(`No workflow type "${frame.name}".`)
382
+ return workflow.run(context)
383
+ }
384
+ case 'render': {
385
+ const render = renderOf(bundle.components?.[frame.name as string])
386
+ if (!render) throw new Error(`No component "${frame.name}".`)
387
+ // Asked of the CMS only when read, since reading them makes the page personal.
388
+ const read = context.readSearchParams
389
+ delete context.readSearchParams
390
+ if (typeof read === 'function')
391
+ Object.defineProperty(context, 'searchParams', {
392
+ get: () => read(),
393
+ enumerable: true,
394
+ })
395
+ return renderToString(render(context) as Child)
396
+ }
397
+ case 'backfill': {
398
+ const step = bundle.tables?.steps.find(
399
+ (candidate: { name: string }) => candidate.name === frame.name,
400
+ )
401
+ if (typeof step?.backfill !== 'function')
402
+ throw new Error(`No backfill for "${frame.name}".`)
403
+ return step.backfill(databaseFor(String(frame.db)))
404
+ }
405
+ default:
406
+ throw new Error(`Unknown call "${frame.kind}".`)
407
+ }
408
+ }
409
+
410
+ async function answer(frame: Frame) {
411
+ const id = frame.id as number
412
+ try {
413
+ const value = await dispatch(frame)
414
+ if (value instanceof Response) {
415
+ send({
416
+ t: 'respond',
417
+ id,
418
+ status: value.status,
419
+ statusText: value.statusText,
420
+ headers: [...value.headers],
421
+ })
422
+ if (value.body) {
423
+ const reader = value.body.getReader()
424
+ for (;;) {
425
+ const { value: chunk, done } = await reader.read()
426
+ if (done) break
427
+ for (let at = 0; at < chunk.length; at += CHUNK_BYTES)
428
+ await send({ t: 'rchunk', id, data: toBase64(chunk.subarray(at, at + CHUNK_BYTES)) })
429
+ }
430
+ }
431
+ send({ t: 'rchunk', id, end: true })
432
+ } else send({ t: 'done', id, value: await encode(value) })
433
+ } catch (error) {
434
+ send({ t: 'error', id, error: await encode(error) })
435
+ }
436
+ }
437
+
438
+ async function start(frame: Frame) {
439
+ dialect = frame.dialect === 'postgres' ? 'postgres' : 'sqlite'
440
+ try {
441
+ const factory = module[exportName]
442
+ if (typeof factory !== 'function')
443
+ throw new Error(
444
+ `The package names "${exportName}" as its server half, which it does not export.`,
445
+ )
446
+ bundle = (await factory(frame.settings ?? {})) as Bundle
447
+ send({ t: 'ready', description: await encode(describe(bundle)) })
448
+ } catch (error) {
449
+ send({ t: 'failed', message: error instanceof Error ? error.message : String(error) })
450
+ }
451
+ }
452
+
453
+ for await (const frame of readFrames(Deno.stdin.readable)) {
454
+ switch (frame.t) {
455
+ case 'init':
456
+ await start(frame)
457
+ break
458
+ case 'call':
459
+ answer(frame)
460
+ break
461
+ case 'reply': {
462
+ const waiter = pending.get(frame.id as number)
463
+ pending.delete(frame.id as number)
464
+ if (!waiter) break
465
+ if (frame.error) waiter.reject(errorFrom(frame.error as { name: string; message: string }))
466
+ else waiter.resolve(frame.value)
467
+ break
468
+ }
469
+ case 'chunk': {
470
+ const body = waiting.get(frame.id as number)
471
+ waiting.delete(frame.id as number)
472
+ if (!body) break
473
+ if (frame.end) body.controller.close()
474
+ else body.controller.enqueue(fromBase64(frame.data as string))
475
+ body.done()
476
+ break
477
+ }
478
+ case 'abort':
479
+ signals.get(frame.signal as number)?.abort()
480
+ break
481
+ case 'ping':
482
+ send({ t: 'pong', id: frame.id })
483
+ break
484
+ }
485
+ }
486
+ Deno.exit(0)
487
+ }
package/src/types.ts ADDED
@@ -0,0 +1,43 @@
1
+ /** The types an extension is written against: erased when it is built, so none of the CMS comes with them. */
2
+
3
+ export type {
4
+ AppAlias,
5
+ BundleCaller,
6
+ BundleCapability,
7
+ BundleDocuments,
8
+ BundleEventHandler,
9
+ BundleEvents,
10
+ BundleForms,
11
+ BundleHost,
12
+ BundleIdentityProviders,
13
+ BundleJob,
14
+ BundleLog,
15
+ BundleMedia,
16
+ BundleMediaCreate,
17
+ BundleMediaDeclaration,
18
+ BundleMediaItem,
19
+ BundleMediaMetadata,
20
+ BundleMediaRefusal,
21
+ BundleMediaUpdate,
22
+ BundleMember,
23
+ BundleMethod,
24
+ BundleRedirectInput,
25
+ BundleRedirectRule,
26
+ BundleRedirects,
27
+ BundleRoute,
28
+ BundleRouteContext,
29
+ BundleSection,
30
+ BundleStep,
31
+ BundleTables,
32
+ ExtensionSectionAlias,
33
+ ImageLocation,
34
+ JobInfo,
35
+ JobSchedule,
36
+ JobStatus,
37
+ OwnerJobs,
38
+ Principal,
39
+ ProviderOverrideInput,
40
+ ServerBundle,
41
+ TablesDatabase,
42
+ } from '@crombolo/crombolo/bundle'
43
+ export type { ShapeOf } from '@crombolo/data/tables-builder'
package/README.md DELETED
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.