@cosmicdrift/kumiko-framework 0.413.0 → 0.413.1
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/agents/api/framework-engine.md +1 -0
- package/agents/examples/helpdesk.md +15 -8
- package/dist/engine/registry-validate.d.ts +1 -0
- package/dist/engine/registry-validate.js +7 -0
- package/dist/engine/registry.js +2 -1
- package/dist/engine/soft-delete-cleanup.js +4 -3
- package/dist/files/feature.js +1 -0
- package/dist/jobs/job-runner-gates.js +5 -1
- package/package.json +3 -3
|
@@ -974,6 +974,7 @@ type JobDefinition = {
|
|
|
974
974
|
runOnBoot?: boolean | undefined;
|
|
975
975
|
bootGate?: boolean | undefined;
|
|
976
976
|
perTenant?: boolean | undefined;
|
|
977
|
+
includeSystemTenant?: boolean | undefined;
|
|
977
978
|
runIn?: JobRunIn | undefined;
|
|
978
979
|
escapeHatch?: EscapeHatchDeclaration | undefined;
|
|
979
980
|
tenantVisibleFailure?: { messageKey: string; subjectFields?: string[] | undefined; } | undefined;
|
|
@@ -18,7 +18,8 @@ SystemAdmins reply from the admin. Phone is off and Telegram is not mounted unle
|
|
|
18
18
|
turns them on (`fields.phone`, `telegram: true`).
|
|
19
19
|
|
|
20
20
|
**What the recipe demonstrates:**
|
|
21
|
-
- Mounting `createHelpdeskFeature` with its companions (delivery, user-data-rights,
|
|
21
|
+
- Mounting `createHelpdeskFeature` with its companions (config, delivery, user-data-rights,
|
|
22
|
+
files, notes-history)
|
|
22
23
|
- The anonymous flow: `helpdesk:query:challenge` hands out a proof-of-work challenge,
|
|
23
24
|
`helpdesk:write:submit` verifies it; spam gets the same 200 body and stores nothing
|
|
24
25
|
- The browser client at `GET /helpdesk/client.js` (`window.KumikoHelpdesk.load()` / `submit()`)
|
|
@@ -48,12 +49,15 @@ bun test --config=bunfig.integration.toml samples/recipes/helpdesk
|
|
|
48
49
|
## Integration into a real app
|
|
49
50
|
|
|
50
51
|
1. Mount `createHelpdeskFeature({ appName })` plus delivery, a mail channel, `user-data-rights`,
|
|
51
|
-
`files` with a file provider and `config`.
|
|
52
|
+
`files` with a file provider, `notes-history` and `config`.
|
|
52
53
|
2. Run `kumiko schema generate` (new tables, plus the delivery `idempotency_key` column).
|
|
53
54
|
3. SystemAdmins set `helpdesk:config:reply-to` in the admin.
|
|
54
|
-
4. Embed `/helpdesk/client.js` on the website; the form is yours.
|
|
55
|
-
|
|
56
|
-
`
|
|
55
|
+
4. Embed `/helpdesk/client.js` on the website; the form is yours. The client posts to the
|
|
56
|
+
relative paths `/api/query` and `/api/write` without cookies, so the page has to share the
|
|
57
|
+
app's origin. A website served by another server forwards `/api` to the app on its own
|
|
58
|
+
origin; it can then serve the same script from `HELPDESK_CLIENT_SOURCE` and type its calls
|
|
59
|
+
with `HelpdeskWebsiteClient`, both from `@cosmicdrift/kumiko-bundled-features/helpdesk/client`.
|
|
60
|
+
`samples/apps/use-all-bundled/public/helpdesk-contact.html` (with `helpdesk-contact.js`) is a complete same-origin page.
|
|
57
61
|
|
|
58
62
|
Telegram is optional and off by default: notifications go by mail to SystemAdmins only. An app
|
|
59
63
|
that turns it on (`telegram: true`) also mounts `channel-telegram` and `secrets` for the bot
|
|
@@ -150,8 +154,10 @@ describe("helpdesk sample", () => {
|
|
|
150
154
|
// captcha: honeypot field, single-use proof-of-work challenge, minimum submit time, per-IP
|
|
151
155
|
// and per-email rate limits. Rejected submits answer 200 with the normal body.
|
|
152
156
|
//
|
|
153
|
-
// The website embeds the anonymous client the feature serves itself
|
|
154
|
-
//
|
|
157
|
+
// The website embeds the anonymous client the feature serves itself. The client posts to the
|
|
158
|
+
// relative paths /api/query and /api/write, so the page must share its origin with the app
|
|
159
|
+
// (or forward /api to it on its own origin):
|
|
160
|
+
// <script src="/helpdesk/client.js"></script>
|
|
155
161
|
// const { kinds, phone } = await window.KumikoHelpdesk.load();
|
|
156
162
|
// const result = await window.KumikoHelpdesk.submit({ kind, name, email, message, locale });
|
|
157
163
|
// // result.kind: "sent" | "rate-limited" (retryAfterSeconds) | "failed"
|
|
@@ -159,7 +165,8 @@ describe("helpdesk sample", () => {
|
|
|
159
165
|
// Prerequisites the app wires itself:
|
|
160
166
|
// - `anonymousAccess` (defaultTenantId = SYSTEM_TENANT_ID) so the form needs no login
|
|
161
167
|
// - delivery with a mail channel (channel-telegram only with `telegram: true`, off by default)
|
|
162
|
-
// -
|
|
168
|
+
// - config, user-data-rights and notes-history (required features)
|
|
169
|
+
// - files with a file provider, because the entities carry file fields
|
|
163
170
|
// - `kumiko schema generate` for the new tables
|
|
164
171
|
|
|
165
172
|
import { createHelpdeskFeature } from "@cosmicdrift/kumiko-bundled-features/helpdesk";
|
|
@@ -27,6 +27,7 @@ export declare function validateLifecycleHookTargets(state: RegistryState): void
|
|
|
27
27
|
export declare function validateEntityHookTargets(state: RegistryState, features: readonly FeatureDefinition[]): void;
|
|
28
28
|
export declare function resolveJobTriggers(state: RegistryState): void;
|
|
29
29
|
export declare function validateLiveEntities(state: RegistryState): void;
|
|
30
|
+
export declare function validateIncludeSystemTenantJobs(state: RegistryState): void;
|
|
30
31
|
export declare function validateBootGates(state: RegistryState): void;
|
|
31
32
|
export declare function validateJobBackoff(state: RegistryState): void;
|
|
32
33
|
export declare function validateMaxDefers(state: RegistryState): void;
|
|
@@ -744,6 +744,13 @@ export function validateLiveEntities(state) {
|
|
|
744
744
|
}
|
|
745
745
|
}
|
|
746
746
|
}
|
|
747
|
+
export function validateIncludeSystemTenantJobs(state) {
|
|
748
|
+
for (const [jobName, jobDef] of state.jobMap) {
|
|
749
|
+
if (jobDef.includeSystemTenant && !jobDef.perTenant) {
|
|
750
|
+
throw new Error(`Job "${jobName}" sets includeSystemTenant without perTenant`);
|
|
751
|
+
}
|
|
752
|
+
}
|
|
753
|
+
}
|
|
747
754
|
export function validateBootGates(state) {
|
|
748
755
|
// Boot gates run inline in JobRunner.start(), which has neither the
|
|
749
756
|
// per-tenant fan-out (that re-enqueues) nor the sequential lock's
|
package/dist/engine/registry.js
CHANGED
|
@@ -4,7 +4,7 @@ import { buildRegistryFacade } from "./registry-facade.js";
|
|
|
4
4
|
import { populateClaimsAndAuth, populateConfigKeys, populateEvents, populateExtensionsAndSeeds, populateFeatureCore, populateHandlers, populateHooks, populateJobsAndNotifications, populateMetricsAndSecrets, populateProjectionsAndTables, populateScreensNavWorkspaces, populateSystemEvents, populateTranslations, } from "./registry-ingest.js";
|
|
5
5
|
import { populateReadModelEntities } from "./registry-read-models.js";
|
|
6
6
|
import { createInitialState } from "./registry-state.js";
|
|
7
|
-
import { applyExtensionUsages, autoWireSoftDeleteJobs, buildEntityEventUpcasterChains, buildEventUpcasterChains, buildImplicitProjections, buildIncomingRelations, buildSearchableSortableCaches, computeHasRateLimitedHandler, finalizeWorkspaceNavMembership, populateHandlerEntityMappings, publishEventPiiCatalog, resolveJobTriggers, resolveNotificationTriggersAndRegisterHooks, validateBootGates, validateEntityHookTargets, validateEventMigrationVersions, validateExtensionSelectors, validateExtensionUsageTargets, validateFieldAccessHandlersAreEntityMapped, validateJobBackoff, validateLifecycleHookTargets, validateLiveEntities, validateMaxDefers, validateMaxPerTenant, validateNotificationRecordMappings, validateNotificationRenamedFrom, validateProjectionApplyKeys, validateRelationTargetsExist, validateRequiredFeatures, } from "./registry-validate.js";
|
|
7
|
+
import { applyExtensionUsages, autoWireSoftDeleteJobs, buildEntityEventUpcasterChains, buildEventUpcasterChains, buildImplicitProjections, buildIncomingRelations, buildSearchableSortableCaches, computeHasRateLimitedHandler, finalizeWorkspaceNavMembership, populateHandlerEntityMappings, publishEventPiiCatalog, resolveJobTriggers, resolveNotificationTriggersAndRegisterHooks, validateBootGates, validateEntityHookTargets, validateEventMigrationVersions, validateExtensionSelectors, validateExtensionUsageTargets, validateFieldAccessHandlersAreEntityMapped, validateIncludeSystemTenantJobs, validateJobBackoff, validateLifecycleHookTargets, validateLiveEntities, validateMaxDefers, validateMaxPerTenant, validateNotificationRecordMappings, validateNotificationRenamedFrom, validateProjectionApplyKeys, validateRelationTargetsExist, validateRequiredFeatures, } from "./registry-validate.js";
|
|
8
8
|
// This is where the magic happens. By "magic" I mean: precomputed maps.
|
|
9
9
|
// I build everything once at boot (hooks, relations, searchable fields, ...)
|
|
10
10
|
// so nothing has to iterate over objects at runtime. O(1) instead of O(n*m).
|
|
@@ -49,6 +49,7 @@ export function createRegistry(rawFeatures) {
|
|
|
49
49
|
validateEntityHookTargets(state, features);
|
|
50
50
|
resolveJobTriggers(state);
|
|
51
51
|
validateBootGates(state);
|
|
52
|
+
validateIncludeSystemTenantJobs(state);
|
|
52
53
|
validateLiveEntities(state);
|
|
53
54
|
validateJobBackoff(state);
|
|
54
55
|
validateMaxDefers(state);
|
|
@@ -62,7 +62,7 @@ export const softDeleteCleanupJob = async (_payload, ctx) => {
|
|
|
62
62
|
if (!db || !registry) {
|
|
63
63
|
throw new Error("soft-delete cleanup: ctx.db + ctx.registry required (JobContext incomplete)");
|
|
64
64
|
}
|
|
65
|
-
// perTenant fan-out → one run per active tenant, systemUser scoped to it.
|
|
65
|
+
// perTenant fan-out → one run per active tenant plus the system tenant, systemUser scoped to it.
|
|
66
66
|
// The job's db is a tenant-filtered TenantDb, but every delete is still
|
|
67
67
|
// explicitly tenant-filtered below as defense-in-depth — otherwise a
|
|
68
68
|
// tenant with a short grace would purge another tenant's still-within-grace
|
|
@@ -73,7 +73,7 @@ export const softDeleteCleanupJob = async (_payload, ctx) => {
|
|
|
73
73
|
return;
|
|
74
74
|
}
|
|
75
75
|
const graceDays = await resolveGraceDays(ctx, tenantId, db);
|
|
76
|
-
const cutoff =
|
|
76
|
+
const cutoff = ctx.tz.now().subtract({ hours: graceDays * 24 });
|
|
77
77
|
for (const proj of registry.getAllProjections().values()) {
|
|
78
78
|
if (proj.isImplicit !== true || typeof proj.source !== "string" || !proj.table)
|
|
79
79
|
continue;
|
|
@@ -143,7 +143,7 @@ export const softDeleteCleanupSystemJob = async (_payload, ctx) => {
|
|
|
143
143
|
if (!db || !registry) {
|
|
144
144
|
throw new Error("soft-delete system cleanup: ctx.db + ctx.registry required (JobContext incomplete)");
|
|
145
145
|
}
|
|
146
|
-
const cutoff =
|
|
146
|
+
const cutoff = ctx.tz.now().subtract({ hours: DEFAULT_GRACE_DAYS * 24 });
|
|
147
147
|
for (const proj of registry.getAllProjections().values()) {
|
|
148
148
|
if (proj.isImplicit !== true || typeof proj.source !== "string" || !proj.table)
|
|
149
149
|
continue;
|
|
@@ -168,6 +168,7 @@ export function buildSoftDeleteCleanupJob() {
|
|
|
168
168
|
handler: softDeleteCleanupJob,
|
|
169
169
|
trigger: { maintenance: true },
|
|
170
170
|
perTenant: true,
|
|
171
|
+
includeSystemTenant: true,
|
|
171
172
|
concurrency: "skip",
|
|
172
173
|
runIn: "worker",
|
|
173
174
|
};
|
package/dist/files/feature.js
CHANGED
|
@@ -42,6 +42,7 @@ export function createFilesFeature(options = {}) {
|
|
|
42
42
|
name: "sweep-orphaned-uploads",
|
|
43
43
|
trigger: { maintenance: true },
|
|
44
44
|
perTenant: true,
|
|
45
|
+
includeSystemTenant: true,
|
|
45
46
|
concurrency: "skip",
|
|
46
47
|
handler: async (_payload, ctx) => {
|
|
47
48
|
await sweepOrphanedUploads({
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
|
|
1
2
|
import { prepareJobRun } from "./job-runner-context.js";
|
|
2
3
|
import { attemptNumberOf, buildRetryBullOpts, DEFER_COUNT_KEY, deferDelayMs, isFinalAttempt, priorAttemptsOf, priorDeferCountOf, } from "./job-runner-helpers.js";
|
|
3
4
|
import { ACTIVE_TENANT_IDS_QUERY_NAME, perTenantChildJobId } from "./job-runner-schedulers.js";
|
|
@@ -35,7 +36,10 @@ async function enqueuePerTenantChildren(scope, bullJob, actualName) {
|
|
|
35
36
|
if (!actualDef) {
|
|
36
37
|
throw new Error(`Unknown job: ${actualName}`);
|
|
37
38
|
}
|
|
38
|
-
const
|
|
39
|
+
const activeTenantIds = await getActiveTenantIds();
|
|
40
|
+
const tenantIds = actualDef.includeSystemTenant === true && !activeTenantIds.includes(SYSTEM_TENANT_ID)
|
|
41
|
+
? [...activeTenantIds, SYSTEM_TENANT_ID]
|
|
42
|
+
: activeTenantIds;
|
|
39
43
|
const targetQueue = scope.queues[laneForJob(actualDef)];
|
|
40
44
|
// wrapperJobId is only absent for a Job BullMQ somehow never assigned
|
|
41
45
|
// an id to (not observed in practice) — falling back to a constant
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cosmicdrift/kumiko-framework",
|
|
3
|
-
"version": "0.413.
|
|
3
|
+
"version": "0.413.1",
|
|
4
4
|
"description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
|
|
@@ -203,7 +203,7 @@
|
|
|
203
203
|
"./package.json": "./package.json"
|
|
204
204
|
},
|
|
205
205
|
"dependencies": {
|
|
206
|
-
"@cosmicdrift/kumiko-types": "0.413.
|
|
206
|
+
"@cosmicdrift/kumiko-types": "0.413.1",
|
|
207
207
|
"bullmq": "^5.81.5",
|
|
208
208
|
"hono": "^4.13.14",
|
|
209
209
|
"i18next": "^26.5.12",
|
|
@@ -225,7 +225,7 @@
|
|
|
225
225
|
}
|
|
226
226
|
},
|
|
227
227
|
"devDependencies": {
|
|
228
|
-
"@cosmicdrift/kumiko-testing": "0.413.
|
|
228
|
+
"@cosmicdrift/kumiko-testing": "0.413.1",
|
|
229
229
|
"bun-types": "^1.4.4",
|
|
230
230
|
"fflate": "^0.8.3",
|
|
231
231
|
"meilisearch": "^0.62.0",
|