@caelo-cms/shared 0.11.8 → 0.11.10
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/certs/aws-rds-global.pem +2888 -0
- package/certs/cloudsql-global.pem +1897 -0
- package/dist/ai-tools.d.ts +2 -2
- package/dist/body-cap.d.ts +35 -0
- package/dist/body-cap.d.ts.map +1 -0
- package/dist/body-cap.js +63 -0
- package/dist/body-cap.js.map +1 -0
- package/dist/build-page.d.ts +4 -4
- package/dist/change-journal.d.ts.map +1 -1
- package/dist/change-journal.js +1 -0
- package/dist/change-journal.js.map +1 -1
- package/dist/client-address.d.ts +69 -0
- package/dist/client-address.d.ts.map +1 -0
- package/dist/client-address.js +99 -0
- package/dist/client-address.js.map +1 -0
- package/dist/content.d.ts +6 -6
- package/dist/content.d.ts.map +1 -1
- package/dist/content.js +8 -1
- package/dist/content.js.map +1 -1
- package/dist/context.d.ts +8 -0
- package/dist/context.d.ts.map +1 -1
- package/dist/database-tls.d.ts +64 -0
- package/dist/database-tls.d.ts.map +1 -0
- package/dist/database-tls.js +95 -0
- package/dist/database-tls.js.map +1 -0
- package/dist/database-url.d.ts +2 -15
- package/dist/database-url.d.ts.map +1 -1
- package/dist/database-url.js +14 -1
- package/dist/database-url.js.map +1 -1
- package/dist/index.d.ts +7 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +7 -0
- package/dist/index.js.map +1 -1
- package/dist/interim-forwarded-host.d.ts +15 -0
- package/dist/interim-forwarded-host.d.ts.map +1 -0
- package/dist/interim-forwarded-host.js +16 -0
- package/dist/interim-forwarded-host.js.map +1 -0
- package/dist/json-security-headers.d.ts +23 -0
- package/dist/json-security-headers.d.ts.map +1 -0
- package/dist/json-security-headers.js +53 -0
- package/dist/json-security-headers.js.map +1 -0
- package/dist/lists/fields.d.ts +6 -0
- package/dist/lists/fields.d.ts.map +1 -1
- package/dist/lists/fields.js +70 -7
- package/dist/lists/fields.js.map +1 -1
- package/dist/lists/index.d.ts +1 -0
- package/dist/lists/index.d.ts.map +1 -1
- package/dist/lists/index.js +1 -0
- package/dist/lists/index.js.map +1 -1
- package/dist/lists/list-type.d.ts +28 -6
- package/dist/lists/list-type.d.ts.map +1 -1
- package/dist/lists/list-type.js +43 -15
- package/dist/lists/list-type.js.map +1 -1
- package/dist/lists/overlay-scope.d.ts +68 -0
- package/dist/lists/overlay-scope.d.ts.map +1 -0
- package/dist/lists/overlay-scope.js +56 -0
- package/dist/lists/overlay-scope.js.map +1 -0
- package/dist/lists/query-merge.d.ts +27 -0
- package/dist/lists/query-merge.d.ts.map +1 -0
- package/dist/lists/query-merge.js +53 -0
- package/dist/lists/query-merge.js.map +1 -0
- package/dist/lists/resolve.d.ts +1 -0
- package/dist/lists/resolve.d.ts.map +1 -1
- package/dist/lists/resolve.js +11 -25
- package/dist/lists/resolve.js.map +1 -1
- package/dist/lists/scope.d.ts +4 -1
- package/dist/lists/scope.d.ts.map +1 -1
- package/dist/pool-budget.d.ts +10 -0
- package/dist/pool-budget.d.ts.map +1 -1
- package/dist/pool-budget.js +15 -0
- package/dist/pool-budget.js.map +1 -1
- package/dist/redirect-emit-gcp.d.ts +16 -8
- package/dist/redirect-emit-gcp.d.ts.map +1 -1
- package/dist/redirect-emit-gcp.js +22 -11
- package/dist/redirect-emit-gcp.js.map +1 -1
- package/dist/release-manifest.d.ts +18 -2
- package/dist/release-manifest.d.ts.map +1 -1
- package/dist/release-manifest.js +32 -4
- package/dist/release-manifest.js.map +1 -1
- package/dist/session-cookie.d.ts +88 -0
- package/dist/session-cookie.d.ts.map +1 -0
- package/dist/session-cookie.js +151 -0
- package/dist/session-cookie.js.map +1 -0
- package/dist/staging-plugin-stub.d.ts +28 -0
- package/dist/staging-plugin-stub.d.ts.map +1 -0
- package/dist/staging-plugin-stub.js +34 -0
- package/dist/staging-plugin-stub.js.map +1 -0
- package/dist/template-engine.d.ts.map +1 -1
- package/dist/template-engine.js +4 -1
- package/dist/template-engine.js.map +1 -1
- package/dist/version.d.ts +2 -2
- package/dist/version.d.ts.map +1 -1
- package/dist/version.js +1 -1
- package/dist/version.js.map +1 -1
- package/package.json +2 -1
- package/src/body-cap.test.ts +44 -0
- package/src/body-cap.ts +83 -0
- package/src/change-journal.ts +1 -0
- package/src/client-address.test.ts +90 -0
- package/src/client-address.ts +111 -0
- package/src/content.test.ts +54 -0
- package/src/content.ts +10 -1
- package/src/context.ts +8 -0
- package/src/database-tls.test.ts +83 -0
- package/src/database-tls.ts +99 -0
- package/src/database-url.test.ts +49 -11
- package/src/database-url.ts +21 -1
- package/src/index.ts +7 -0
- package/src/interim-forwarded-host.ts +16 -0
- package/src/json-security-headers.test.ts +31 -0
- package/src/json-security-headers.ts +53 -0
- package/src/lists/fields.ts +88 -7
- package/src/lists/index.ts +1 -0
- package/src/lists/list-type.ts +53 -18
- package/src/lists/lists.test.ts +70 -0
- package/src/lists/overlay-scope.test.ts +140 -0
- package/src/lists/overlay-scope.ts +120 -0
- package/src/lists/pagination.test.ts +15 -0
- package/src/lists/query-merge.ts +84 -0
- package/src/lists/resolve.test.ts +24 -4
- package/src/lists/resolve.ts +12 -33
- package/src/lists/scope.ts +4 -2
- package/src/pool-budget.test.ts +17 -3
- package/src/pool-budget.ts +19 -0
- package/src/redirect-emit-gcp.ts +24 -11
- package/src/redirect-emit.test.ts +6 -5
- package/src/release-manifest.ts +33 -4
- package/src/session-cookie.test.ts +96 -0
- package/src/session-cookie.ts +163 -0
- package/src/staging-plugin-stub.test.ts +23 -0
- package/src/staging-plugin-stub.ts +37 -0
- package/src/template-engine-lists.test.ts +27 -1
- package/src/template-engine.ts +4 -1
- package/src/version.ts +1 -1
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
// SPDX-License-Identifier: MPL-2.0
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* #1223 — what one previewed page can show from lists: the scope of its
|
|
5
|
+
* `list-resolve` call, or null when it shows nothing an overlay changes.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import { describe, expect, it } from "bun:test";
|
|
9
|
+
import type { TemplateField } from "../template-engine.js";
|
|
10
|
+
import type { ListTypeDef } from "./list-type.js";
|
|
11
|
+
import { pageListOverlayScope, type ScopedModule } from "./overlay-scope.js";
|
|
12
|
+
import type { ListPageRecord, ListRenderData } from "./render-data.js";
|
|
13
|
+
|
|
14
|
+
const P = (n: number): string => `00000000-0000-4000-8000-${String(n).padStart(12, "0")}`;
|
|
15
|
+
const CI = "00000000-0000-4000-9000-000000000001";
|
|
16
|
+
|
|
17
|
+
function page(id: string, pageTypeSlug: string): ListPageRecord {
|
|
18
|
+
return {
|
|
19
|
+
id,
|
|
20
|
+
title: id,
|
|
21
|
+
shortTitle: id,
|
|
22
|
+
parentId: null,
|
|
23
|
+
pageTypeSlug,
|
|
24
|
+
properties: {},
|
|
25
|
+
terms: [],
|
|
26
|
+
firstPublishedAt: null,
|
|
27
|
+
updatedAt: "2026-10-01T00:00:00.000Z",
|
|
28
|
+
summary: null,
|
|
29
|
+
image: null,
|
|
30
|
+
inBuild: true,
|
|
31
|
+
} as ListPageRecord;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
function listType(slug: string, source?: { kind: string; name?: string }): ListTypeDef {
|
|
35
|
+
return {
|
|
36
|
+
slug,
|
|
37
|
+
name: slug,
|
|
38
|
+
purpose: slug,
|
|
39
|
+
role: "content",
|
|
40
|
+
root: { allow: ["entry"] },
|
|
41
|
+
nodes: {
|
|
42
|
+
entry: { label: "Entry", fields: [{ name: "label", label: "Label", type: "text" }] },
|
|
43
|
+
...(source ? { feed: { label: "Feed", fields: [], source } } : {}),
|
|
44
|
+
},
|
|
45
|
+
} as ListTypeDef;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** P(1) en (product), P(2) de (product), P(3) de (plain), P(4) de (product). */
|
|
49
|
+
const data = {
|
|
50
|
+
listTypes: new Map([
|
|
51
|
+
["nav", { id: "t1", def: listType("nav") }],
|
|
52
|
+
["feed", { id: "t2", def: listType("feed", { kind: "query" }) }],
|
|
53
|
+
["langs", { id: "t3", def: listType("langs", { kind: "plugin", name: "language_links" }) }],
|
|
54
|
+
]),
|
|
55
|
+
lists: new Map([
|
|
56
|
+
["l2", { id: "l2", slug: "footer", name: "Footer", typeSlug: "nav", items: [] }],
|
|
57
|
+
["l1", { id: "l1", slug: "menu", name: "Menu", typeSlug: "nav", items: [] }],
|
|
58
|
+
]),
|
|
59
|
+
pageTypes: new Map([
|
|
60
|
+
[
|
|
61
|
+
"product",
|
|
62
|
+
{
|
|
63
|
+
id: "pt1",
|
|
64
|
+
def: { slug: "product", properties: [{ name: "tagline", label: "T", type: "text" }] },
|
|
65
|
+
},
|
|
66
|
+
],
|
|
67
|
+
["plain", { id: "pt2", def: { slug: "plain", properties: [] } }],
|
|
68
|
+
]),
|
|
69
|
+
pages: new Map([
|
|
70
|
+
[P(1), page(P(1), "product")],
|
|
71
|
+
[P(2), page(P(2), "product")],
|
|
72
|
+
[P(3), page(P(3), "plain")],
|
|
73
|
+
[P(4), page(P(4), "product")],
|
|
74
|
+
]),
|
|
75
|
+
media: new Map(),
|
|
76
|
+
pageVariants: new Map([
|
|
77
|
+
[P(1), { variant: "en", group: "g1" }],
|
|
78
|
+
[P(2), { variant: "de", group: "g1" }],
|
|
79
|
+
[P(3), { variant: "de", group: null }],
|
|
80
|
+
[P(4), { variant: "de", group: "g2" }],
|
|
81
|
+
]),
|
|
82
|
+
siteLanguage: "en",
|
|
83
|
+
homePageId: null,
|
|
84
|
+
} as unknown as ListRenderData;
|
|
85
|
+
|
|
86
|
+
const field = (f: Partial<TemplateField> & { name: string }): TemplateField =>
|
|
87
|
+
({ kind: "text", ...f }) as TemplateField;
|
|
88
|
+
const mod = (fields: TemplateField[], html = ""): ScopedModule => ({ fields, html });
|
|
89
|
+
|
|
90
|
+
function scopeOf(modules: ScopedModule[], markup: string[] = []) {
|
|
91
|
+
return pageListOverlayScope({
|
|
92
|
+
pageId: P(2),
|
|
93
|
+
data,
|
|
94
|
+
modules,
|
|
95
|
+
markup,
|
|
96
|
+
contentInstanceIds: [CI, CI],
|
|
97
|
+
});
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
describe("pageListOverlayScope (#1223)", () => {
|
|
101
|
+
it("is null for a page that shows no list, no page value and no site text", () => {
|
|
102
|
+
expect(scopeOf([mod([field({ name: "title" })], "<h1>{{title}}</h1>")])).toBeNull();
|
|
103
|
+
});
|
|
104
|
+
|
|
105
|
+
it("covers every shared list, the page's instances and the page itself", () => {
|
|
106
|
+
expect(scopeOf([mod([field({ name: "items", kind: "list", listType: "nav" })])])).toEqual({
|
|
107
|
+
listIds: ["l1", "l2"],
|
|
108
|
+
contentInstanceIds: [CI],
|
|
109
|
+
pageIds: [P(2)],
|
|
110
|
+
});
|
|
111
|
+
});
|
|
112
|
+
|
|
113
|
+
it("counts `page.*` and `site_text.*` in any markup as a list read", () => {
|
|
114
|
+
const plain = [mod([field({ name: "title" })], "<h1>{{title}}</h1>")];
|
|
115
|
+
expect(scopeOf([mod([], "<p>{{ PAGE.props.tagline }}</p>")])?.pageIds).toEqual([P(2)]);
|
|
116
|
+
expect(scopeOf(plain, ["<footer>{{site_text.copyright}}</footer>"])).not.toBeNull();
|
|
117
|
+
});
|
|
118
|
+
|
|
119
|
+
it("adds the variant's pages with properties when a list generates page entries", () => {
|
|
120
|
+
const query = scopeOf([mod([field({ name: "news", kind: "list", listType: "feed" })])]);
|
|
121
|
+
// P(3) has no properties, P(1) is in another variant.
|
|
122
|
+
expect(query?.pageIds).toEqual([P(2), P(4)]);
|
|
123
|
+
const bound = scopeOf([
|
|
124
|
+
mod([
|
|
125
|
+
field({
|
|
126
|
+
name: "kids",
|
|
127
|
+
kind: "list",
|
|
128
|
+
bind: "source",
|
|
129
|
+
source: { kind: "system", name: "children" },
|
|
130
|
+
} as never),
|
|
131
|
+
]),
|
|
132
|
+
]);
|
|
133
|
+
expect(bound?.pageIds).toEqual([P(2), P(4)]);
|
|
134
|
+
});
|
|
135
|
+
|
|
136
|
+
it("a plugin source generates no pages", () => {
|
|
137
|
+
const langs = scopeOf([mod([field({ name: "langs", kind: "list", listType: "langs" })])]);
|
|
138
|
+
expect(langs?.pageIds).toEqual([P(2)]);
|
|
139
|
+
});
|
|
140
|
+
});
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
// SPDX-License-Identifier: MPL-2.0
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* #1223 — what one page's render can show from lists, so the editor
|
|
5
|
+
* preview asks `list-resolve` for that page's overlay instead of the whole
|
|
6
|
+
* site's (the plugin's answer then costs what the page costs).
|
|
7
|
+
*
|
|
8
|
+
* An overlay is keyed by value address (`list/<listId>/…`,
|
|
9
|
+
* `instance/<ciId>/…`, `page/<pageId>/props/…`, docs/lists.md §9.3). The
|
|
10
|
+
* resolver reads it lazily while the page renders, so the scope has to be
|
|
11
|
+
* known before the render and has to be a SUPERSET of what the render
|
|
12
|
+
* reads; anything more only costs a few rows:
|
|
13
|
+
*
|
|
14
|
+
* - lists: every shared list. A list renders as a whole wherever it is
|
|
15
|
+
* bound (a menu, the site texts, a vocabulary's terms), and their
|
|
16
|
+
* number does not grow with the pages.
|
|
17
|
+
* - content instances: the instances the page renders (its placements
|
|
18
|
+
* and the instances nested in them), whose local lists the overlay
|
|
19
|
+
* translates.
|
|
20
|
+
* - pages: the rendered page (`{{page.props.*}}`) and, when a list on
|
|
21
|
+
* the page generates page entries (a query or a system source:
|
|
22
|
+
* latest news, children, breadcrumbs), every page of the page's
|
|
23
|
+
* variant that has properties. A props overlay only exists for pages
|
|
24
|
+
* of the variant the page renders, and only for page types that
|
|
25
|
+
* declare properties, so no other page can show one.
|
|
26
|
+
*
|
|
27
|
+
* Null when the page shows nothing a list overlay can change: no module
|
|
28
|
+
* on it (placed, chrome, nested or a content variant) has a list field,
|
|
29
|
+
* and no markup reads `page.*` or `site_text.*`. The preview then skips
|
|
30
|
+
* `list-resolve` entirely.
|
|
31
|
+
*
|
|
32
|
+
* The static build asks per page batch with the union of its pages'
|
|
33
|
+
* scopes (#1307, the generator's `list-overlay-batches.ts`), so a build's
|
|
34
|
+
* `list-resolve` reads cost what the batch costs, not the site.
|
|
35
|
+
*/
|
|
36
|
+
|
|
37
|
+
import type { TemplateField } from "../template-engine.js";
|
|
38
|
+
import type { ListRenderData } from "./render-data.js";
|
|
39
|
+
|
|
40
|
+
/** The `scope` of a scoped `list-resolve` call (plugin-sdk `listResolveScope`). */
|
|
41
|
+
export interface ListOverlayScope {
|
|
42
|
+
readonly listIds: string[];
|
|
43
|
+
readonly contentInstanceIds: string[];
|
|
44
|
+
readonly pageIds: string[];
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** A module field as far as the scope cares (a build's fields may leave `kind` out: text). */
|
|
48
|
+
export type ScopedField = Omit<TemplateField, "kind"> & { readonly kind?: string };
|
|
49
|
+
|
|
50
|
+
/** A module as far as the scope cares: its fields and its markup. */
|
|
51
|
+
export interface ScopedModule {
|
|
52
|
+
readonly fields: readonly ScopedField[];
|
|
53
|
+
readonly html: string;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** What {@link pageListOverlayScope} reads the page from. */
|
|
57
|
+
export interface PageListOverlayInput {
|
|
58
|
+
readonly pageId: string;
|
|
59
|
+
/** The page's list render data before overlays (pages, lists, types, partition). */
|
|
60
|
+
readonly data: ListRenderData;
|
|
61
|
+
/** Every module the page renders: placed, chrome, nested, content variants. */
|
|
62
|
+
readonly modules: Iterable<ScopedModule>;
|
|
63
|
+
/** Markup outside the modules: the template's and the layout's HTML. */
|
|
64
|
+
readonly markup: Iterable<string>;
|
|
65
|
+
/** The stored content instances the page renders (render-local aliases excluded). */
|
|
66
|
+
readonly contentInstanceIds: Iterable<string>;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* `{{page.…}}` / `{{site_text.…}}` (any case, any section operator). A
|
|
71
|
+
* loose match on purpose: a false hit costs one scoped plugin call, a
|
|
72
|
+
* miss would show the page untranslated.
|
|
73
|
+
*/
|
|
74
|
+
const LIST_SCOPE_READ_RE = /\b(?:page|site_text)\./i;
|
|
75
|
+
|
|
76
|
+
/** True when the module's markup or fields can read list data. */
|
|
77
|
+
function readsLists(m: ScopedModule): boolean {
|
|
78
|
+
return m.fields.some((f) => f.kind === "list") || LIST_SCOPE_READ_RE.test(m.html);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** True when one of `fields` can generate page entries (a query or system source). */
|
|
82
|
+
function generatesPages(fields: readonly ScopedField[], data: ListRenderData): boolean {
|
|
83
|
+
for (const f of fields) {
|
|
84
|
+
if (f.kind !== "list") continue;
|
|
85
|
+
if (f.bind === "source" && f.source?.kind !== "plugin") return true;
|
|
86
|
+
const type = f.listType === undefined ? undefined : data.listTypes.get(f.listType);
|
|
87
|
+
if (!type) continue;
|
|
88
|
+
for (const node of Object.values(type.def.nodes)) {
|
|
89
|
+
if (node.source && node.source.kind !== "plugin") return true;
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
return false;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* The scope of one page's `list-resolve` call, or null when the page
|
|
97
|
+
* shows nothing an overlay can change (see the file header).
|
|
98
|
+
*/
|
|
99
|
+
export function pageListOverlayScope(input: PageListOverlayInput): ListOverlayScope | null {
|
|
100
|
+
const { data, pageId } = input;
|
|
101
|
+
const modules = [...input.modules];
|
|
102
|
+
const usesLists =
|
|
103
|
+
modules.some(readsLists) || [...input.markup].some((html) => LIST_SCOPE_READ_RE.test(html));
|
|
104
|
+
if (!usesLists) return null;
|
|
105
|
+
|
|
106
|
+
const pageIds = new Set<string>([pageId]);
|
|
107
|
+
const variant = data.pageVariants?.get(pageId)?.variant;
|
|
108
|
+
if (variant !== undefined && modules.some((m) => generatesPages(m.fields, data))) {
|
|
109
|
+
for (const p of data.pages.values()) {
|
|
110
|
+
if (data.pageVariants?.get(p.id)?.variant !== variant) continue;
|
|
111
|
+
if ((data.pageTypes.get(p.pageTypeSlug)?.def.properties.length ?? 0) === 0) continue;
|
|
112
|
+
pageIds.add(p.id);
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
return {
|
|
116
|
+
listIds: [...data.lists.keys()].sort(),
|
|
117
|
+
contentInstanceIds: [...new Set(input.contentInstanceIds)].sort(),
|
|
118
|
+
pageIds: [...pageIds].sort(),
|
|
119
|
+
};
|
|
120
|
+
}
|
|
@@ -226,6 +226,21 @@ describe("module field schema", () => {
|
|
|
226
226
|
});
|
|
227
227
|
|
|
228
228
|
describe("resolver", () => {
|
|
229
|
+
// #1281 review — a paginated query without order must not be told to add
|
|
230
|
+
// a limit: paginateIssues refuses a limit next to paginate.
|
|
231
|
+
it("a paginated query without order names order, never a limit", () => {
|
|
232
|
+
const noOrder: ListFieldSpec = {
|
|
233
|
+
...GUIDES,
|
|
234
|
+
source: { kind: "query", editable: [], defaults: { page_type: "guide" } },
|
|
235
|
+
};
|
|
236
|
+
const r = ctxFor(3).resolveField(noOrder, undefined, { contentInstanceId: null });
|
|
237
|
+
expect(r).toMatchObject({ ok: false, marker: "list-malformed:guides[query.order]" });
|
|
238
|
+
const detail = r.ok ? "" : (r.detail ?? "");
|
|
239
|
+
expect(detail).toContain('the query has no "order"');
|
|
240
|
+
expect(detail).toContain("paginate:{}");
|
|
241
|
+
expect(detail).not.toContain("limit:");
|
|
242
|
+
});
|
|
243
|
+
|
|
229
244
|
it("shows 50 per page by default and records the sequence", () => {
|
|
230
245
|
const ctx = ctxFor(63);
|
|
231
246
|
const page1 = resolve(ctx, GUIDES);
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
// SPDX-License-Identifier: MPL-2.0
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Merging a query source's defaults with the knobs an entry or placement
|
|
5
|
+
* sets (`docs/lists.md` §6). A query that does not come out complete is
|
|
6
|
+
* never guessed (CLAUDE.md §2): the render reports
|
|
7
|
+
* `list-malformed:<field>[<path>.<knob>]`, the marker names the failing
|
|
8
|
+
* knob, and `detail` says how to fix it — `preview_list_source` hands it to
|
|
9
|
+
* the AI verbatim (#1281).
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
import {
|
|
13
|
+
PAGINATED_QUERY_SOURCE_EXAMPLE,
|
|
14
|
+
type PageQuery,
|
|
15
|
+
pageQuerySchema,
|
|
16
|
+
QUERY_SOURCE_EXAMPLE,
|
|
17
|
+
type QueryKnob,
|
|
18
|
+
type SourceDef,
|
|
19
|
+
} from "./list-type.js";
|
|
20
|
+
|
|
21
|
+
/** Why a merged query failed: the marker the render reports + the fix. */
|
|
22
|
+
export interface QueryMergeFailure {
|
|
23
|
+
readonly marker: string;
|
|
24
|
+
readonly detail: string;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
const ORDER_VALUES =
|
|
28
|
+
'"published_desc", "published_asc", "title_asc", "prop_desc:<property>" or "prop_asc:<property>"';
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* Merge `source.defaults` with `overrides` (an entry's / placement's knobs)
|
|
32
|
+
* and parse the result as a complete page query.
|
|
33
|
+
*
|
|
34
|
+
* @param field The list field the source belongs to (marker prefix).
|
|
35
|
+
* @param path Where the overrides live (`query`, `<itemId>.query`).
|
|
36
|
+
* @param paginated The field is paginated: its page size is the limit, so
|
|
37
|
+
* the fix never suggests one (a limit next to paginate is refused).
|
|
38
|
+
*/
|
|
39
|
+
export function mergeQuerySource(
|
|
40
|
+
source: Extract<SourceDef, { kind: "query" }>,
|
|
41
|
+
overrides: unknown,
|
|
42
|
+
field: string,
|
|
43
|
+
path: string,
|
|
44
|
+
paginated = false,
|
|
45
|
+
): PageQuery | QueryMergeFailure {
|
|
46
|
+
const fail = (at: string, detail: string): QueryMergeFailure => ({
|
|
47
|
+
marker: `list-malformed:${field}[${at}]`,
|
|
48
|
+
detail,
|
|
49
|
+
});
|
|
50
|
+
const merged: Record<string, unknown> = { ...source.defaults };
|
|
51
|
+
const editable: readonly string[] = source.editable;
|
|
52
|
+
if (overrides !== undefined && overrides !== null) {
|
|
53
|
+
if (typeof overrides !== "object" || Array.isArray(overrides)) {
|
|
54
|
+
return fail(path, "the value of a query field is an object of query knobs, e.g. {limit:3}.");
|
|
55
|
+
}
|
|
56
|
+
for (const [k, v] of Object.entries(overrides)) {
|
|
57
|
+
if (!editable.includes(k as QueryKnob)) {
|
|
58
|
+
return fail(
|
|
59
|
+
`${path}.${k}`,
|
|
60
|
+
`"${k}" cannot be set per entry or placement — the source's editable list is ${editable.length > 0 ? editable.join(", ") : "empty"}. Remove "${k}" from the value, or add it to source.editable.`,
|
|
61
|
+
);
|
|
62
|
+
}
|
|
63
|
+
merged[k] = v;
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
const parsed = pageQuerySchema.safeParse(merged);
|
|
67
|
+
if (parsed.success) return parsed.data;
|
|
68
|
+
const issue = parsed.error.issues[0];
|
|
69
|
+
const knob = issue?.path.map(String).join(".") ?? "";
|
|
70
|
+
const at = knob === "" ? path : `${path}.${knob}`;
|
|
71
|
+
if (knob === "order" && merged.order === undefined) {
|
|
72
|
+
return fail(
|
|
73
|
+
at,
|
|
74
|
+
`the query has no "order" — add order (${ORDER_VALUES}) to source.defaults, e.g. ${paginated ? PAGINATED_QUERY_SOURCE_EXAMPLE : QUERY_SOURCE_EXAMPLE}.`,
|
|
75
|
+
);
|
|
76
|
+
}
|
|
77
|
+
if (knob === "limit" && merged.limit === undefined) {
|
|
78
|
+
return fail(
|
|
79
|
+
at,
|
|
80
|
+
`the query has no "limit" — add limit (1–50) to source.defaults, e.g. ${QUERY_SOURCE_EXAMPLE}; for an overview of every matching page, give the list field paginate:{} instead.`,
|
|
81
|
+
);
|
|
82
|
+
}
|
|
83
|
+
return fail(at, `query knob "${knob}" is invalid: ${issue?.message ?? "invalid value"}.`);
|
|
84
|
+
}
|
|
@@ -104,14 +104,34 @@ describe("query sources", () => {
|
|
|
104
104
|
const q = query({ page_type: "news", order: "published_desc", limit: 3 }, ["limit"]);
|
|
105
105
|
expect(entries(page(PAGE.home), q, { limit: 1 })).toHaveLength(1);
|
|
106
106
|
const r = page(PAGE.home).resolveField(q, { page_type: "page" }, { contentInstanceId: null });
|
|
107
|
-
expect(r).
|
|
107
|
+
expect(r).toMatchObject({ ok: false, marker: "list-malformed:q[query.page_type]" });
|
|
108
|
+
expect(r.ok ? "" : r.detail).toContain(
|
|
109
|
+
'"page_type" cannot be set per entry or placement — the source\'s editable list is limit.',
|
|
110
|
+
);
|
|
108
111
|
});
|
|
109
112
|
|
|
110
|
-
|
|
111
|
-
|
|
113
|
+
// #1281 — the marker names the missing knob and `detail` says the fix
|
|
114
|
+
// (preview_list_source used to blame the `editable` list instead).
|
|
115
|
+
it("an incomplete query (no order / limit) is malformed, never guessed — naming the knob", () => {
|
|
116
|
+
const noOrder = page(PAGE.home).resolveField(query({ page_type: "news" }), undefined, {
|
|
112
117
|
contentInstanceId: null,
|
|
113
118
|
});
|
|
114
|
-
expect(
|
|
119
|
+
expect(noOrder).toMatchObject({ ok: false, marker: "list-malformed:q[query.order]" });
|
|
120
|
+
expect(noOrder.ok ? "" : noOrder.detail).toContain('the query has no "order" — add order (');
|
|
121
|
+
const noLimit = page(PAGE.home).resolveField(
|
|
122
|
+
query({ page_type: "news", order: "title_asc" }),
|
|
123
|
+
undefined,
|
|
124
|
+
{ contentInstanceId: null },
|
|
125
|
+
);
|
|
126
|
+
expect(noLimit).toMatchObject({ ok: false, marker: "list-malformed:q[query.limit]" });
|
|
127
|
+
expect(noLimit.ok ? "" : noLimit.detail).toContain('the query has no "limit"');
|
|
128
|
+
const badLimit = page(PAGE.home).resolveField(
|
|
129
|
+
query({ page_type: "news", order: "title_asc", limit: 3 }, ["limit"]),
|
|
130
|
+
{ limit: 500 },
|
|
131
|
+
{ contentInstanceId: null },
|
|
132
|
+
);
|
|
133
|
+
expect(badLimit).toMatchObject({ ok: false, marker: "list-malformed:q[query.limit]" });
|
|
134
|
+
expect(badLimit.ok ? "" : badLimit.detail).toContain('query knob "limit" is invalid');
|
|
115
135
|
});
|
|
116
136
|
|
|
117
137
|
it("returns only pages of the rendering page's variant", () => {
|
package/src/lists/resolve.ts
CHANGED
|
@@ -34,8 +34,6 @@ import {
|
|
|
34
34
|
type ListTypeDef,
|
|
35
35
|
type NodeDef,
|
|
36
36
|
type PageQuery,
|
|
37
|
-
pageQuerySchema,
|
|
38
|
-
type QueryKnob,
|
|
39
37
|
type SourceDef,
|
|
40
38
|
type SystemSourceName,
|
|
41
39
|
} from "./list-type.js";
|
|
@@ -49,6 +47,7 @@ import {
|
|
|
49
47
|
pagedUrl,
|
|
50
48
|
splitPaginationValue,
|
|
51
49
|
} from "./pagination.js";
|
|
50
|
+
import { mergeQuerySource } from "./query-merge.js";
|
|
52
51
|
import { parseListRef } from "./refs.js";
|
|
53
52
|
import type {
|
|
54
53
|
ListPageRecord,
|
|
@@ -107,7 +106,7 @@ export interface ListFieldSpec {
|
|
|
107
106
|
/** Result of resolving one list field for one page. */
|
|
108
107
|
export type ListFieldResolution =
|
|
109
108
|
| { readonly ok: true; readonly entries: readonly ScopeEntry[] }
|
|
110
|
-
| { readonly ok: false; readonly marker: string };
|
|
109
|
+
| { readonly ok: false; readonly marker: string; readonly detail?: string };
|
|
111
110
|
|
|
112
111
|
/**
|
|
113
112
|
* Where a local list is stored: the content instance holding the module
|
|
@@ -1098,29 +1097,6 @@ function createPageContext(
|
|
|
1098
1097
|
);
|
|
1099
1098
|
};
|
|
1100
1099
|
|
|
1101
|
-
/** Merge a source's query defaults with the knobs an entry / placement may set. */
|
|
1102
|
-
const mergedQuery = (
|
|
1103
|
-
source: Extract<SourceDef, { kind: "query" }>,
|
|
1104
|
-
overrides: unknown,
|
|
1105
|
-
field: string,
|
|
1106
|
-
path: string,
|
|
1107
|
-
): PageQuery | { marker: string } => {
|
|
1108
|
-
const merged: Record<string, unknown> = { ...source.defaults };
|
|
1109
|
-
if (overrides !== undefined && overrides !== null) {
|
|
1110
|
-
if (typeof overrides !== "object" || Array.isArray(overrides)) {
|
|
1111
|
-
return { marker: `list-malformed:${field}[${path}]` };
|
|
1112
|
-
}
|
|
1113
|
-
for (const [k, v] of Object.entries(overrides)) {
|
|
1114
|
-
if (!(source.editable as readonly string[]).includes(k as QueryKnob)) {
|
|
1115
|
-
return { marker: `list-malformed:${field}[${path}.${k}]` };
|
|
1116
|
-
}
|
|
1117
|
-
merged[k] = v;
|
|
1118
|
-
}
|
|
1119
|
-
}
|
|
1120
|
-
const parsed = pageQuerySchema.safeParse(merged);
|
|
1121
|
-
return parsed.success ? parsed.data : { marker: `list-malformed:${field}[${path}]` };
|
|
1122
|
-
};
|
|
1123
|
-
|
|
1124
1100
|
/** Generated entries of a source node (`{{#items}}`). */
|
|
1125
1101
|
const sourceItems = (
|
|
1126
1102
|
source: SourceDef,
|
|
@@ -1130,8 +1106,10 @@ function createPageContext(
|
|
|
1130
1106
|
): ScopeValue => {
|
|
1131
1107
|
switch (source.kind) {
|
|
1132
1108
|
case "query": {
|
|
1133
|
-
const q =
|
|
1134
|
-
return "marker" in q
|
|
1109
|
+
const q = mergeQuerySource(source, item.query, field, `${item.id}.query`);
|
|
1110
|
+
return "marker" in q
|
|
1111
|
+
? { kind: "failed", marker: q.marker, detail: q.detail }
|
|
1112
|
+
: runQuery(q, field);
|
|
1135
1113
|
}
|
|
1136
1114
|
case "system": {
|
|
1137
1115
|
const termFields = node.fields.filter((f) => f.type === "term");
|
|
@@ -1153,7 +1131,7 @@ function createPageContext(
|
|
|
1153
1131
|
|
|
1154
1132
|
const fromValue = (v: ScopeValue): ListFieldResolution =>
|
|
1155
1133
|
v.kind === "failed"
|
|
1156
|
-
? { ok: false, marker: v.marker }
|
|
1134
|
+
? { ok: false, marker: v.marker, ...(v.detail !== undefined ? { detail: v.detail } : {}) }
|
|
1157
1135
|
: { ok: true, entries: v.kind === "list" ? v.entries : [] };
|
|
1158
1136
|
|
|
1159
1137
|
/**
|
|
@@ -1172,13 +1150,14 @@ function createPageContext(
|
|
|
1172
1150
|
if (eff === null) return { ok: false, marker: `list-malformed:${field.name}[paginate]` };
|
|
1173
1151
|
const source = field.source;
|
|
1174
1152
|
if (source?.kind === "query") {
|
|
1175
|
-
const q =
|
|
1153
|
+
const q = mergeQuerySource(
|
|
1176
1154
|
{ ...source, defaults: { ...source.defaults, limit: eff.perPage } },
|
|
1177
1155
|
rest,
|
|
1178
1156
|
field.name,
|
|
1179
1157
|
"query",
|
|
1158
|
+
true,
|
|
1180
1159
|
);
|
|
1181
|
-
if ("marker" in q) return { ok: false, marker: q.marker };
|
|
1160
|
+
if ("marker" in q) return { ok: false, marker: q.marker, detail: q.detail };
|
|
1182
1161
|
const key = JSON.stringify(["query", { ...q, limit: null }]);
|
|
1183
1162
|
return fromValue(paginate(field.name, key, queryHits(q), eff));
|
|
1184
1163
|
}
|
|
@@ -1207,9 +1186,9 @@ function createPageContext(
|
|
|
1207
1186
|
if (!source) return { ok: false, marker: `list-malformed:${field.name}[source]` };
|
|
1208
1187
|
switch (source.kind) {
|
|
1209
1188
|
case "query": {
|
|
1210
|
-
const q =
|
|
1189
|
+
const q = mergeQuerySource(source, value, field.name, "query");
|
|
1211
1190
|
return "marker" in q
|
|
1212
|
-
? { ok: false, marker: q.marker }
|
|
1191
|
+
? { ok: false, marker: q.marker, detail: q.detail }
|
|
1213
1192
|
: fromValue(runQuery(q, field.name));
|
|
1214
1193
|
}
|
|
1215
1194
|
case "system": {
|
package/src/lists/scope.ts
CHANGED
|
@@ -42,9 +42,11 @@ export type ScopeValue =
|
|
|
42
42
|
/**
|
|
43
43
|
* A value that could not resolve (a list source of an inactive plugin,
|
|
44
44
|
* a malformed query). The engine renders the tag raw and reports
|
|
45
|
-
* `marker` — loud, never silently empty (CLAUDE.md §2).
|
|
45
|
+
* `marker` — loud, never silently empty (CLAUDE.md §2). `detail`, when
|
|
46
|
+
* set, says what is wrong and how to fix it (shown to the AI by
|
|
47
|
+
* `preview_list_source`, #1281).
|
|
46
48
|
*/
|
|
47
|
-
| { readonly kind: "failed"; readonly marker: string };
|
|
49
|
+
| { readonly kind: "failed"; readonly marker: string; readonly detail?: string };
|
|
48
50
|
|
|
49
51
|
/** One entry a list section iterates. */
|
|
50
52
|
export interface ScopeEntry {
|
package/src/pool-budget.test.ts
CHANGED
|
@@ -10,8 +10,10 @@ import {
|
|
|
10
10
|
DB_POOL_MAX_ENV,
|
|
11
11
|
DB_PUBLIC_POOL_MAX_ENV,
|
|
12
12
|
GATEWAY_POOL_MAX,
|
|
13
|
+
GATEWAY_ROLE_CONNECTION_LIMIT,
|
|
13
14
|
GENERATOR_POOL_MAX,
|
|
14
15
|
LISTEN_CONNECTIONS_PER_ADMIN_INSTANCE,
|
|
16
|
+
LISTEN_CONNECTIONS_PER_GATEWAY_INSTANCE,
|
|
15
17
|
type PoolBudgetInput,
|
|
16
18
|
poolBudgetEnv,
|
|
17
19
|
} from "./pool-budget.js";
|
|
@@ -67,15 +69,27 @@ describe("computePoolBudget", () => {
|
|
|
67
69
|
});
|
|
68
70
|
|
|
69
71
|
it("refuses a budget below the admin floor, naming the connections needed", () => {
|
|
70
|
-
//
|
|
71
|
-
expect(() => computePoolBudget({ ...GCP_DEFAULT,
|
|
72
|
-
/Raise maxConnections to at least
|
|
72
|
+
// Ten gateway instances on 60 slots: 30 for the gateway leave too little.
|
|
73
|
+
expect(() => computePoolBudget({ ...GCP_DEFAULT, maxConnections: 60 })).toThrow(
|
|
74
|
+
/Raise maxConnections to at least 94/,
|
|
73
75
|
);
|
|
74
76
|
expect(() => computePoolBudget({ ...GCP_DEFAULT, maxConnections: 50 })).toThrow(
|
|
75
77
|
new RegExp(`minimum of ${ADMIN_POOL_FLOOR}`),
|
|
76
78
|
);
|
|
77
79
|
});
|
|
78
80
|
|
|
81
|
+
it("refuses a gateway scale-out beyond public_role's CONNECTION LIMIT (#1338)", () => {
|
|
82
|
+
expect(GATEWAY_ROLE_CONNECTION_LIMIT).toBe(
|
|
83
|
+
10 * (GATEWAY_POOL_MAX + LISTEN_CONNECTIONS_PER_GATEWAY_INSTANCE),
|
|
84
|
+
);
|
|
85
|
+
expect(() =>
|
|
86
|
+
computePoolBudget({ ...GCP_DEFAULT, maxConnections: 1000, gatewayMaxInstances: 11 }),
|
|
87
|
+
).toThrow(
|
|
88
|
+
"11 gateway instances need 33 connections, but the database lets the gateway's login (public_role) hold at most 30",
|
|
89
|
+
);
|
|
90
|
+
expect(() => computePoolBudget({ ...GCP_DEFAULT, gatewayMaxInstances: 10 })).not.toThrow();
|
|
91
|
+
});
|
|
92
|
+
|
|
79
93
|
it("accepts exactly the floor", () => {
|
|
80
94
|
// reserves 74 + 5 × 4 = 94.
|
|
81
95
|
expect(computePoolBudget({ ...GCP_DEFAULT, maxConnections: 94 }).adminPoolMax).toBe(4);
|
package/src/pool-budget.ts
CHANGED
|
@@ -78,6 +78,17 @@ export const LISTEN_CONNECTIONS_PER_ADMIN_INSTANCE = 1;
|
|
|
78
78
|
*/
|
|
79
79
|
export const LISTEN_CONNECTIONS_PER_GATEWAY_INSTANCE = 1;
|
|
80
80
|
|
|
81
|
+
/**
|
|
82
|
+
* #1338 — public_role's `CONNECTION LIMIT` (cms_admin migration 0500,
|
|
83
|
+
* bootstrap.sh; the role audit's `PUBLIC_ROLE_LIMITS` pins the same value):
|
|
84
|
+
* the gateway's share at ten instances, `10 × (GATEWAY_POOL_MAX +
|
|
85
|
+
* LISTEN_CONNECTIONS_PER_GATEWAY_INSTANCE)`. The database refuses the
|
|
86
|
+
* gateway's connections beyond it, so {@link computePoolBudget} refuses a
|
|
87
|
+
* scale-out that would need more instead of letting instances fail to
|
|
88
|
+
* connect under load.
|
|
89
|
+
*/
|
|
90
|
+
export const GATEWAY_ROLE_CONNECTION_LIMIT = 30;
|
|
91
|
+
|
|
81
92
|
/** What the budget is computed from: the server and the scale-out limits. */
|
|
82
93
|
export interface PoolBudgetInput {
|
|
83
94
|
/** The server's `max_connections`, as provisioning sets it. */
|
|
@@ -173,6 +184,14 @@ export function computePoolBudget(input: PoolBudgetInput): PoolBudget {
|
|
|
173
184
|
positiveInteger(input.maintenanceReserve, "maintenanceReserve", 0);
|
|
174
185
|
positiveInteger(input.migrationsReserve, "migrationsReserve", 0);
|
|
175
186
|
positiveInteger(input.jobsReserve, "jobsReserve", 0);
|
|
187
|
+
const gatewayConnections =
|
|
188
|
+
input.gatewayMaxInstances * (GATEWAY_POOL_MAX + LISTEN_CONNECTIONS_PER_GATEWAY_INSTANCE);
|
|
189
|
+
if (gatewayConnections > GATEWAY_ROLE_CONNECTION_LIMIT) {
|
|
190
|
+
throw new Error(
|
|
191
|
+
`pool budget: ${input.gatewayMaxInstances} gateway instances need ${gatewayConnections} connections, but the database lets the gateway's login (public_role) hold at most ${GATEWAY_ROLE_CONNECTION_LIMIT} (CONNECTION LIMIT, #1338). ` +
|
|
192
|
+
`Lower gatewayMaxInstances to at most ${Math.floor(GATEWAY_ROLE_CONNECTION_LIMIT / (GATEWAY_POOL_MAX + LISTEN_CONNECTIONS_PER_GATEWAY_INSTANCE))}.`,
|
|
193
|
+
);
|
|
194
|
+
}
|
|
176
195
|
|
|
177
196
|
const reserves: PoolBudgetReserve[] = [
|
|
178
197
|
{ name: "maintenance", connections: input.maintenanceReserve },
|
package/src/redirect-emit-gcp.ts
CHANGED
|
@@ -161,19 +161,32 @@ export function assertGcpRedirectBudget(
|
|
|
161
161
|
withGcpRedirects({ name: "budget-check", pathRules: baseRules }, plan);
|
|
162
162
|
}
|
|
163
163
|
|
|
164
|
+
/** The paths the `gcp` load balancer sends to the visitor gateway: its whole API. */
|
|
165
|
+
export const GCP_GATEWAY_PATHS: readonly string[] = ["/api/*"];
|
|
166
|
+
|
|
164
167
|
/**
|
|
165
|
-
*
|
|
166
|
-
*
|
|
167
|
-
*
|
|
168
|
-
*
|
|
169
|
-
*
|
|
170
|
-
*
|
|
171
|
-
*
|
|
172
|
-
* `openid-configuration` prefix: the broker
|
|
173
|
-
* serves no such document (#899), so the site
|
|
168
|
+
* #1328 — the paths the `gcp` load balancer sends to the MCP-Auth-Proxy, the
|
|
169
|
+
* remote-MCP broker's own service (#806 put it inside the gateway). The
|
|
170
|
+
* endpoints and the broker's OAuth routes under `/api/mcp/*` — the more
|
|
171
|
+
* specific prefix wins over `/api/*` in one path matcher — and the two
|
|
172
|
+
* `/.well-known/oauth-*` prefixes, the broker's discovery documents, which
|
|
173
|
+
* MCP clients look up at the host root (RFC 9728 protected-resource
|
|
174
|
+
* metadata, RFC 8414 authorization-server metadata); they must reach the
|
|
175
|
+
* proxy, not 404 in the bucket. No `openid-configuration` prefix: the broker
|
|
176
|
+
* is not an OpenID provider and serves no such document (#899), so the site
|
|
177
|
+
* keeps that path.
|
|
174
178
|
*/
|
|
175
|
-
export const
|
|
176
|
-
"/api/*",
|
|
179
|
+
export const GCP_MCP_AUTH_PROXY_PATHS: readonly string[] = [
|
|
180
|
+
"/api/mcp/*",
|
|
177
181
|
"/.well-known/oauth-protected-resource/*",
|
|
178
182
|
"/.well-known/oauth-authorization-server/*",
|
|
179
183
|
];
|
|
184
|
+
|
|
185
|
+
/**
|
|
186
|
+
* The site's own routing in the `public` path matcher (stack + budget): the
|
|
187
|
+
* paths the load balancer sends to a service instead of the static bucket.
|
|
188
|
+
*/
|
|
189
|
+
export const GCP_PUBLIC_BASE_PATHS: readonly string[] = [
|
|
190
|
+
...GCP_GATEWAY_PATHS,
|
|
191
|
+
...GCP_MCP_AUTH_PROXY_PATHS,
|
|
192
|
+
];
|