@classytic/arc 2.51.0 → 2.53.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/README.md +2 -1
- package/dist/{EventTransport-K7Q9WPjm.mjs → EventTransport-B3jTKMQH.mjs} +2 -2
- package/dist/{HookSystem-DBAu9uNT.mjs → HookSystem-DNwxV463.mjs} +2 -2
- package/dist/{ResourceRegistry-BelzCRMy.mjs → ResourceRegistry-Ck7RFodL.mjs} +2 -2
- package/dist/{acquire-B0zhfGSm.mjs → acquire-DkLruwhL.mjs} +1 -1
- package/dist/audit/index.d.mts +1 -1
- package/dist/audit/index.mjs +4 -4
- package/dist/auth/audit.mjs +1 -1
- package/dist/auth/index.d.mts +1 -1
- package/dist/auth/index.mjs +7 -7
- package/dist/auth/redis-session.mjs +1 -1
- package/dist/auth/social/index.mjs +1 -1
- package/dist/{authorizationDecision-Dxj_cy6N.mjs → authorizationDecision-gB5-bHDp.mjs} +9 -7
- package/dist/bootError-BT3z3cvX.mjs +38 -0
- package/dist/{boundedMap-DOBai-H3.mjs → boundedMap-Ddw2yGb2.mjs} +1 -1
- package/dist/{buildHandler-Dyl8P9j0.mjs → buildHandler-B8IDGmhD.mjs} +5 -5
- package/dist/cache/index.mjs +4 -4
- package/dist/{caching-CUmaNL8Y.mjs → caching-BitJDAY0.mjs} +2 -2
- package/dist/{claimed-DJPk4VZr.mjs → claimed-CM_-lFHX.mjs} +1 -1
- package/dist/cleanup/index.d.mts +2 -2
- package/dist/cleanup/index.mjs +4 -4
- package/dist/cli/commands/describe.d.mts +18 -1
- package/dist/cli/commands/describe.mjs +39 -7
- package/dist/cli/commands/docs.mjs +3 -3
- package/dist/cli/commands/doctor.d.mts +3 -1
- package/dist/cli/commands/doctor.mjs +135 -22
- package/dist/cli/commands/generate.mjs +2 -2
- package/dist/cli/commands/init.mjs +2 -2
- package/dist/cli/commands/introspect.mjs +2 -2
- package/dist/cli/index.mjs +3 -3
- package/dist/{constants-DH41jnNT.mjs → constants-D9EiaO5s.mjs} +1 -1
- package/dist/context/index.d.mts +5 -2
- package/dist/context/index.mjs +5 -5
- package/dist/core/index.d.mts +2 -2
- package/dist/core/index.mjs +7 -7
- package/dist/{core-DPmRWlpx.mjs → core-B_06Fcn0.mjs} +3 -3
- package/dist/{createActionRouter-B1xhER6i.mjs → createActionRouter-DtxUXOCI.mjs} +5 -5
- package/dist/{createAggregationRouter-CNntJL-z.mjs → createAggregationRouter-BMiKyDoW.mjs} +7 -7
- package/dist/{createApp-DpG26bCu.mjs → createApp-CEdGZtkP.mjs} +207 -44
- package/dist/{createMcpServer-CS2KOVP6.d.mts → createMcpServer-Bk3ls5jS.d.mts} +1 -1
- package/dist/{defineAggregation-rI3EbZUg.mjs → defineAggregation-DUsrGcsm.mjs} +1 -1
- package/dist/{defineResource-5DcG_wlI.mjs → defineResource-q8TsJpOm.mjs} +92 -36
- package/dist/deprecation-DX625dth.mjs +27 -0
- package/dist/discovery/index.mjs +1 -1
- package/dist/docs/index.d.mts +1 -1
- package/dist/docs/index.mjs +3 -3
- package/dist/{elevation-XFu7J3aj.mjs → elevation-NJ3908pJ.mjs} +5 -5
- package/dist/encryption/index.d.mts +26 -1
- package/dist/encryption/index.mjs +56 -6
- package/dist/{errorHandler-xDVUWOMu.mjs → errorHandler-Ke6PGvF7.mjs} +7 -4
- package/dist/{errors-KBZ3tQk5.mjs → errors-Ukhmfmmx.mjs} +1 -1
- package/dist/{eventPlugin-BY38F6yK.d.mts → eventPlugin-BeJasppx.d.mts} +7 -18
- package/dist/{eventPlugin-C4lNj2Dw.mjs → eventPlugin-DTKAgSvb.mjs} +10 -8
- package/dist/{eventTypes-DZRoUAdk.mjs → eventTypes-DpDQtyR6.mjs} +2 -2
- package/dist/events/index.d.mts +2 -2
- package/dist/events/index.mjs +8 -8
- package/dist/events/transports/redis-stream-entry.mjs +4 -4
- package/dist/events/transports/redis.mjs +2 -2
- package/dist/factory/index.d.mts +28 -5
- package/dist/factory/index.mjs +12 -7
- package/dist/{fastify-augmentation-baQc3MaO.d.mts → fastify-augmentation-DjxuSRG4.d.mts} +4 -3
- package/dist/{fieldTypes-DrXUW1jc.mjs → fieldTypes-BtFpQO6I.mjs} +2 -2
- package/dist/{fields-C5J8WTd2.mjs → fields-B7fuROWK.mjs} +1 -1
- package/dist/{filter-merge-DTjYoDrj.mjs → filter-merge-BuzZ-r9z.mjs} +1 -1
- package/dist/{generate-SA8oMlLB.mjs → generate-c4F39pk1.mjs} +4 -4
- package/dist/{headers-D5wrBLOk.mjs → headers-Ib7BDgRI.mjs} +2 -2
- package/dist/{health-BLal039H.mjs → health-22T82HAa.mjs} +1 -1
- package/dist/health-skjSwNaC.d.mts +36 -0
- package/dist/hooks/index.d.mts +1 -1
- package/dist/hooks/index.mjs +2 -2
- package/dist/http-cache/index.mjs +4 -4
- package/dist/http-cache/purgers/cloudflare.mjs +2 -2
- package/dist/http-cache/purgers/fastly.mjs +2 -2
- package/dist/http-cache/testing/index.mjs +1 -1
- package/dist/idempotency/index.d.mts +7 -1
- package/dist/idempotency/index.mjs +9 -7
- package/dist/idempotency/redis.mjs +2 -2
- package/dist/{index-CMNpMBtW.d.mts → index-BzUyno-u.d.mts} +14 -5
- package/dist/{index-Dhrks-hM.d.mts → index-CXqYFGoH.d.mts} +13 -4
- package/dist/{index-DexdFs1a.d.mts → index-CaBFPmnu.d.mts} +29 -7
- package/dist/{index-DKM2p5w5.d.mts → index-DWn0o4U7.d.mts} +2 -2
- package/dist/{index-DLCcLUQT.d.mts → index-DtHACefu.d.mts} +109 -116
- package/dist/index.d.mts +5 -5
- package/dist/index.mjs +12 -12
- package/dist/{init-DeKHaNZn.mjs → init-XY5slyuS.mjs} +3 -3
- package/dist/integrations/event-gateway.mjs +2 -2
- package/dist/integrations/index.d.mts +1 -1
- package/dist/integrations/index.mjs +1 -1
- package/dist/integrations/jobs/index.mjs +3 -3
- package/dist/integrations/mcp/index.d.mts +9 -4
- package/dist/integrations/mcp/index.mjs +2 -2
- package/dist/integrations/mcp/testing.d.mts +2 -2
- package/dist/integrations/mcp/testing.mjs +2 -2
- package/dist/integrations/streamline.mjs +3 -3
- package/dist/integrations/webhooks.d.mts +1 -1
- package/dist/integrations/webhooks.mjs +4 -4
- package/dist/integrations/websocket-pushref-redis.mjs +1 -1
- package/dist/integrations/websocket-redis.mjs +1 -1
- package/dist/integrations/websocket.mjs +2 -2
- package/dist/invariants-COekUeoh.mjs +120 -0
- package/dist/{jsonBody-rDPGT5A9.mjs → jsonBody-BNlcGUnb.mjs} +2 -2
- package/dist/{keys-t7i-lJ2r.mjs → keys-DwvXJwUX.mjs} +1 -1
- package/dist/{loadResources-CcupAVJH.mjs → loadResources-izEeQLO_.mjs} +3 -3
- package/dist/{loadResourcesFromEntry-BpjYlaoj.mjs → loadResourcesFromEntry-CijqjbHE.mjs} +2 -2
- package/dist/logger/index.mjs +2 -2
- package/dist/{logger-IL7Btm-N.mjs → logger-DdMS0XC_.mjs} +1 -1
- package/dist/{mcpPlugin-BsdH7Vot.mjs → mcpPlugin-D0tSZqKk.mjs} +24 -22
- package/dist/{memory-Dkp6ZD3F.mjs → memory-Ay0haw9n.mjs} +3 -3
- package/dist/{metrics-CDPqgdKr.mjs → metrics-Bpgf4UL6.mjs} +3 -3
- package/dist/middleware/index.d.mts +1 -1
- package/dist/middleware/index.mjs +3 -3
- package/dist/migrations/index.mjs +2 -2
- package/dist/{module-KFxT1Iuk.mjs → module-BLrTmMyk.mjs} +17 -2
- package/dist/{multiTenant-QtDzxx_K.d.mts → multiTenant-Cf0Ye-Wu.d.mts} +1 -1
- package/dist/{multipartBody-BHktuarE.mjs → multipartBody-L2gr96df.mjs} +1 -1
- package/dist/{observeSend-CY-sLanc.mjs → observeSend-B7FEdk_g.mjs} +1 -1
- package/dist/{openapi-DbeXiy2v.mjs → openapi-COrL_33P.mjs} +6 -6
- package/dist/outbox-admin/index.d.mts +1 -1
- package/dist/outbox-admin/index.mjs +6 -6
- package/dist/{outbox-module-BWqkTE8-.mjs → outbox-module-BY2HtnjU.mjs} +7 -7
- package/dist/{outbox-module-DzW6zwWJ.d.mts → outbox-module-C1QWMloZ.d.mts} +5 -8
- package/dist/permissions/index.d.mts +2 -2
- package/dist/permissions/index.mjs +8 -8
- package/dist/{permissions-e5YMrFbm.mjs → permissions-CEyeDHtT.mjs} +36 -17
- package/dist/{pipe-CMnKfdF4.mjs → pipe-DIAr91at.mjs} +2 -2
- package/dist/pipeline/index.d.mts +1 -1
- package/dist/pipeline/index.mjs +2 -2
- package/dist/{plan-BvLJGm3U.mjs → plan-BhKHIkFl.mjs} +75 -20
- package/dist/{plugin-DYmu8uT4.mjs → plugin-D6hrdx-j.mjs} +72 -38
- package/dist/plugins/index.d.mts +4 -3
- package/dist/plugins/index.mjs +18 -18
- package/dist/plugins/response-cache.mjs +4 -4
- package/dist/plugins/tracing-entry.mjs +177 -85
- package/dist/{pluralize-ClwfBdIx.mjs → pluralize-CJKgYkVc.mjs} +1 -1
- package/dist/presetPermission-2pcRVYRG.mjs +23 -0
- package/dist/presets/filesUpload.d.mts +4 -2
- package/dist/presets/filesUpload.mjs +11 -6
- package/dist/presets/index.d.mts +6 -4
- package/dist/presets/index.mjs +2 -2
- package/dist/presets/multiTenant.d.mts +1 -1
- package/dist/presets/multiTenant.mjs +5 -5
- package/dist/presets/search.d.mts +2 -2
- package/dist/presets/search.mjs +54 -38
- package/dist/{presets-DX_lPabi.mjs → presets-st11ePNn.mjs} +150 -41
- package/dist/{projection-DnZiFPPE.mjs → projection-B4rqiJTi.mjs} +2 -2
- package/dist/{purger.types-BEzTVDOU.mjs → purger.types-BcHeAhY_.mjs} +1 -1
- package/dist/{queryCachePlugin-C57-Nj-g.mjs → queryCachePlugin-BgSc2bga.mjs} +6 -6
- package/dist/rateLimitKey-DLGdeFd2.mjs +138 -0
- package/dist/{realtime-C-VIoXMg.mjs → realtime-CpYpIFsm.mjs} +11 -11
- package/dist/registry/index.d.mts +2 -2
- package/dist/registry/index.mjs +3 -3
- package/dist/{registry-DbQvODPH.mjs → registry-BQsdAlZ_.mjs} +2 -2
- package/dist/{relay-B61seKq1.mjs → relay-CmT3gtkP.mjs} +11 -12
- package/dist/{renewingLease-Dp7wmzNN.mjs → renewingLease-DaoP0K-e.mjs} +1 -1
- package/dist/{replyHelpers-CHii_jIO.mjs → replyHelpers-SiLr1wK4.mjs} +2 -2
- package/dist/{requestContext-C_mbAm8o.mjs → requestContext-B-TjFpWt.mjs} +8 -3
- package/dist/{health-vEo3fni4.mjs → requestId-ClcKoWLq.mjs} +154 -116
- package/dist/{requirement-C8OsWLYp.mjs → requirement-BygDzjDS.mjs} +1 -1
- package/dist/{resourceRateLimit-DhbQZjE2.mjs → resourceRateLimit-DdIYis3m.mjs} +2 -2
- package/dist/{rolldown-runtime-HTi8KV7V.mjs → rolldown-runtime-Cy6j0m8_.mjs} +1 -1
- package/dist/{routeValidator-DnQ2BGnH.mjs → routeValidator-Bn-x2gaJ.mjs} +1 -1
- package/dist/{runtimeCapabilities-G9QXHov1.mjs → runtimeCapabilities-DY20Pibh.mjs} +7 -2
- package/dist/{schedules-DAthT5O3.mjs → schedules-CwqC0Mp0.mjs} +5 -5
- package/dist/{schemaConverter-BOt_ed78.mjs → schemaConverter-XoLKVpzG.mjs} +2 -2
- package/dist/{schemaIR-MZVVj6Cw.mjs → schemaIR-DP7mMj7c.mjs} +16 -16
- package/dist/schemas/index.mjs +1 -1
- package/dist/scim/index.mjs +2 -2
- package/dist/scope/index.d.mts +6 -2
- package/dist/scope/index.mjs +5 -5
- package/dist/{scope-btg-225w.mjs → scope-B0vgM2Zw.mjs} +4 -4
- package/dist/{shutdown-Dfy8La90.mjs → shutdown-C76Hn-Th.mjs} +1 -1
- package/dist/{simpleEqualityMatcher-D5dOqbbj.mjs → simpleEqualityMatcher-Qbl-11cE.mjs} +1 -1
- package/dist/{sse-DivxX1m6.mjs → sse-eyb8lNuI.mjs} +7 -7
- package/dist/{sseStream-hQxQjvre.mjs → sseStream-BsBesrfw.mjs} +2 -2
- package/dist/{store-helpers-DfqfssAw.mjs → store-helpers-D1yIVa91.mjs} +1 -1
- package/dist/{streaming-CQiOktsh.mjs → streaming-DKziqs1Z.mjs} +1 -1
- package/dist/{subscriberIdentity-Bf8VLqA7.mjs → subscriberIdentity-DpdSQMQq.mjs} +1 -1
- package/dist/{tenancy-Btmaf1MB.mjs → tenancy-YuRYsOPr.mjs} +2 -2
- package/dist/{tenantPreparation-4e3qyb6q.mjs → tenantPreparation-Bk8ouRB3.mjs} +17 -5
- package/dist/testing/cleanupStoreContract.mjs +1 -1
- package/dist/testing/index.d.mts +4 -4
- package/dist/testing/index.mjs +11 -11
- package/dist/testing/outboxStoreContract.mjs +2 -2
- package/dist/testing/requiredPorts.d.mts +1 -1
- package/dist/testing/requiredPorts.mjs +2 -2
- package/dist/testing/storageContract.mjs +1 -1
- package/dist/{timing-DXx0IWyi.mjs → timing-BtIDIdQz.mjs} +1 -1
- package/dist/{transactionContext-DperjON1.mjs → transactionContext-BsQ5ortM.mjs} +1 -1
- package/dist/{typeGuards-eoQLIOh6.mjs → typeGuards-Cr2_zEW0.mjs} +1 -1
- package/dist/types/index.d.mts +2 -2
- package/dist/types/index.mjs +1 -1
- package/dist/types/storage.mjs +1 -1
- package/dist/{types-BeEJm-DV.d.mts → types-CQhHTZXs.d.mts} +48 -35
- package/dist/{types-B4E0sc6D.d.mts → types-DWFgq8EP.d.mts} +1 -1
- package/dist/{types-CcpISJe8.mjs → types-ZvdR7MVa.mjs} +4 -4
- package/dist/usage/index.mjs +4 -4
- package/dist/{userHelpers-Cp5zqlEN.mjs → userHelpers-CwpEK36a.mjs} +1 -1
- package/dist/utils/index.d.mts +1 -1
- package/dist/utils/index.mjs +12 -12
- package/dist/{utils-dKN-_315.mjs → utils-CnrfcYMq.mjs} +6 -6
- package/dist/{validate-BZHaAdgy.mjs → validate-BTQBh-Dr.mjs} +3 -3
- package/dist/{versioning-CPLP0VbB.mjs → versioning-DiLykI6U.mjs} +3 -3
- package/dist/{workScope-BI72KXsI.mjs → workScope-C3tPz_Gt.mjs} +2 -2
- package/package.json +34 -9
- package/skills/arc/SKILL.md +5 -5
- package/skills/arc/references/api-reference.md +1 -1
- package/skills/arc/references/boot.md +17 -2
- package/skills/arc/references/events.md +0 -1
- package/skills/arc/references/mcp-setup.md +3 -2
- package/skills/arc/references/multi-tenancy.md +1 -1
- package/skills/arc/references/production-api.md +19 -12
- package/skills/arc/references/production-audit.md +1 -1
- package/skills/arc/references/production-boot.md +3 -3
- package/skills/arc/references/production-idempotency.md +2 -2
- package/skills/arc/references/production-observability.md +14 -2
- package/skills/arc/references/production-reliability.md +1 -1
- package/skills/arc/references/querying.md +1 -2
- package/skills/arc/references/resources.md +8 -6
- package/skills/arc/references/testing.md +1 -1
- package/skills/arc-code-review/references/arc-cheatsheet.md +1 -1
- package/skills/arc-code-review/references/recipe-scope-permissions.md +1 -1
- package/skills/arc-module-publishing/references/resource-assembly.md +2 -2
- package/dist/rateLimitKey-B1RxyGt3.mjs +0 -40
|
@@ -63,26 +63,33 @@ Reads `accept-version` (`headerName`), sets `x-api-version` (`responseHeader`) a
|
|
|
63
63
|
## Rate limiting
|
|
64
64
|
|
|
65
65
|
```typescript
|
|
66
|
-
import { createTenantKeyGenerator } from '@classytic/arc/scope';
|
|
67
|
-
|
|
68
66
|
createApp({
|
|
69
67
|
rateLimit: {
|
|
70
|
-
max: 100, timeWindow: '1 minute',
|
|
71
|
-
redis,
|
|
72
|
-
|
|
73
|
-
skipPaths: ['/api/auth/*'],
|
|
68
|
+
max: 100, timeWindow: '1 minute', // per signed-in user; per IP when anonymous
|
|
69
|
+
redis, // shared store, required with runtime 'distributed'
|
|
70
|
+
ipCeiling: 2000, // early per-IP flood guard (default max(2000, 20 × max)); false drops it
|
|
74
71
|
},
|
|
75
72
|
});
|
|
76
73
|
```
|
|
77
74
|
|
|
78
|
-
|
|
75
|
+
Default key (no `keyGenerator`, no `plan`): the signed-in user's id when the scope has one, else the client IP (IPv6 grouped by /64). It runs at `preHandler`, after auth, so one office Wi-Fi or carrier NAT never throttles colleagues together, while sign-in, sign-up and reset (no user yet) stay limited per IP. An `allowList` of addresses also matches signed-in callers from those addresses. The `ipCeiling` counts every request per IP at `onRequest` (before auth, unmatched routes included) on the same store; routes with `config: { rateLimit: false }` skip it.
|
|
76
|
+
|
|
77
|
+
Pick another key with `createTenantKeyGenerator` (`@classytic/arc/scope`); arc moves it to `preHandler` too:
|
|
78
|
+
|
|
79
|
+
```typescript
|
|
80
|
+
import { createTenantKeyGenerator } from '@classytic/arc/scope';
|
|
81
|
+
|
|
82
|
+
rateLimit: { max: 1000, keyGenerator: createTenantKeyGenerator({ strategy: 'organization' }) } // one quota per org
|
|
83
|
+
rateLimit: { max: 100, keyGenerator: (req) => req.ip } // per IP, as before 2.53
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
| `strategy` | Key |
|
|
79
87
|
|---|---|
|
|
80
|
-
| `
|
|
81
|
-
| `
|
|
82
|
-
| `
|
|
83
|
-
| `public` | IP |
|
|
88
|
+
| `'user'` (createApp default) | `user:<userId>`, else IP |
|
|
89
|
+
| `'organization'` (when omitted) | `member`/`service`: `organizationId`; `authenticated`: `userId`; `elevated`: `organizationId ?? userId`; `public`: IP |
|
|
90
|
+
| `(ctx) => string` | yours (`ctx.ip`, `ctx.scope`) |
|
|
84
91
|
|
|
85
|
-
|
|
92
|
+
A host `keyGenerator` or `plan` gets no `ipCeiling`. Per-resource budgets: `defineResource({ rateLimit })`.
|
|
86
93
|
|
|
87
94
|
Shared store down (`redis`/`store`): every call is bounded (`storeFallback.timeoutMs`, 250) and an error or timeout is answered from per-instance memory counters (still limited, never hangs or 500s); one warning per outage, probed every `retryAfterMs` (5000), resumes on its first answer; `storeFallback.onStatus` reports each switch for a health/metrics signal. `storeFallback: false` = the plugin's own behaviour.
|
|
88
95
|
|
|
@@ -64,7 +64,7 @@ const deleted = await fastify.audit.purge(new Date(Date.now() - 90 * 86_400_000)
|
|
|
64
64
|
defineResource({
|
|
65
65
|
name: 'audit-log',
|
|
66
66
|
adapter: auditAdapter, // adapter over the audit repository
|
|
67
|
-
|
|
67
|
+
crud: { list: true, get: true },
|
|
68
68
|
queryParser: new QueryParser({ allowedFilterFields: ['resource', 'documentId', 'userId', 'action', 'organizationId'] }),
|
|
69
69
|
permissions: { list: requireRoles(['auditor']), get: requireRoles(['auditor']) },
|
|
70
70
|
});
|
|
@@ -65,14 +65,14 @@ export default { fetch: toFetchHandler(app) };
|
|
|
65
65
|
|
|
66
66
|
- Unset `methods` → arc's verbs (`GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS`), not `@fastify/cors`'s `GET,HEAD,POST`, when `origin` is an explicit allow-list (string, array, RegExp). `origin: true` or a function keeps `GET,HEAD,POST` (boot warning with `credentials: true`). Any resolved list that omits a verb your routes use (e.g. `origin: true` without credentials vs CRUD `PATCH`/`DELETE`) logs one `onReady` warning naming the verbs.
|
|
67
67
|
- Production without `cors.origin` warns. `origin: '*'` with `credentials: true` throws at boot; use an allow-list.
|
|
68
|
-
- Arc merges its headers (`x-organization-id`, `x-arc-scope`, `x-request-id`) into a declared `allowedHeaders` list and always exposes its own response headers
|
|
69
|
-
- Mobile webviews (Capacitor, Ionic): add webview origins
|
|
68
|
+
- Arc merges its headers (`x-organization-id`, `x-arc-scope`, `x-request-id`) into a declared `allowedHeaders` list and always exposes its own response headers (`set-auth-token`, `x-request-id`), so browser code can read the request id that error bodies quote as `correlationId`.
|
|
69
|
+
- Mobile webviews (Capacitor, Ionic): add webview origins; arc already exposes the Better Auth bearer header.
|
|
70
70
|
|
|
71
71
|
```typescript
|
|
72
72
|
cors: {
|
|
73
73
|
origin: [...webOrigins, 'https://localhost', 'capacitor://localhost'],
|
|
74
74
|
credentials: true,
|
|
75
|
-
exposedHeaders: ['
|
|
75
|
+
exposedHeaders: ['x-total-count'], // your own headers; arc adds set-auth-token and x-request-id
|
|
76
76
|
},
|
|
77
77
|
trustProxy: true,
|
|
78
78
|
```
|
|
@@ -40,7 +40,7 @@ Boot fails when a listed op is not mounted or the plugin is disabled. Custom rou
|
|
|
40
40
|
|
|
41
41
|
```typescript
|
|
42
42
|
routes: [{
|
|
43
|
-
method: 'POST', path: '/:id/charge', handler:
|
|
43
|
+
method: 'POST', path: '/:id/charge', handler: (ctx) => payments.charge(ctx),
|
|
44
44
|
config: { idempotency: { required: true } }, // any method, DELETE included
|
|
45
45
|
}]
|
|
46
46
|
// action routes: { requiredActions: ['refund'] }
|
|
@@ -74,7 +74,7 @@ repository: new Repository(IdempotencyModel, [methodRegistryPlugin(), batchOpera
|
|
|
74
74
|
|
|
75
75
|
## IdempotencyStore contract
|
|
76
76
|
|
|
77
|
-
Required: `name`, `get`, `set`, `tryLock`, `unlock`, `isLocked`, `delete`, `deleteByPrefix`, `findByPrefix`. Optional: `acquire` (atomic check-and-lock), `setIfLocked` (fenced completion), `supportsFencedCompletion`, `completionReleasesLock`, `close`. A custom store
|
|
77
|
+
Required: `name`, `get`, `set`, `tryLock`, `unlock`, `isLocked`, `delete`, `deleteByPrefix`, `findByPrefix`. Optional: `acquire` (atomic check-and-lock), `setIfLocked` (fenced completion), `supportsFencedCompletion`, `completionReleasesLock`, `close`. A custom store must implement `setIfLocked`. `unlock` after a non-2xx must leave no claim behind (the repository store deletes a result-less row it locks).
|
|
78
78
|
|
|
79
79
|
## Gotchas
|
|
80
80
|
|
|
@@ -25,12 +25,15 @@ Manual: `fastify.register(healthPlugin, opts)` from `@classytic/arc/plugins`; `c
|
|
|
25
25
|
| Route | Response |
|
|
26
26
|
|---|---|
|
|
27
27
|
| `GET /_health` and `/_health/live` | 200 `{ status: 'ok', timestamp, version? }` |
|
|
28
|
-
| `GET /_health/ready` | 200 `{ status: 'ready', timestamp, checks: [{ name, healthy, duration
|
|
28
|
+
| `GET /_health/ready` | 200 `{ status: 'ready', timestamp, checks: [{ name, healthy, duration }] }`; error text goes to the log only |
|
|
29
29
|
| ready, critical check failed | 503 `status: 'not_ready'` |
|
|
30
30
|
| ready, shutdown draining | 503 `status: 'draining'` (liveness stays 200) |
|
|
31
31
|
|
|
32
32
|
- `critical` defaults to true; only critical failures return 503.
|
|
33
33
|
- Health-check names must be unique across the app (duplicates throw at boot).
|
|
34
|
+
- Modules contribute checks with `defineModule({ healthChecks })` (static; resolve deps lazily inside `check`).
|
|
35
|
+
- At ready, every check runs once and one `[arc] boot health: N/M passing ...` line is logged; never fatal. Under `production` with no critical check, the line says so.
|
|
36
|
+
- Import `HealthCheck` from `@classytic/arc/plugins`.
|
|
34
37
|
- `metrics: true` adds `/_health/metrics` with process metrics; `metricsCollector` replaces the body.
|
|
35
38
|
|
|
36
39
|
## Request id
|
|
@@ -61,7 +64,16 @@ Programmatic: `fastify.metrics.recordOperation(resource, op, status, durationMs)
|
|
|
61
64
|
|
|
62
65
|
## Tracing (OpenTelemetry)
|
|
63
66
|
|
|
64
|
-
|
|
67
|
+
Explicit opt-in, OpenTelemetry JS SDK 3.x. Core (else a no-op with one warning, `isTracingAvailable()` false):
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
npm i @opentelemetry/api@^1.10.0 @opentelemetry/sdk-trace@^3.1.1 @opentelemetry/resources@^3.1.1 @opentelemetry/semantic-conventions@^1.45.0
|
|
71
|
+
npm i @opentelemetry/exporter-trace-otlp-http@^0.301.2 @opentelemetry/context-async-hooks@^3.1.1 # export + async context
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Each other package loads on its own and is named once when missing: the OTLP exporter (warn: spans not exported), `context-async-hooks` (warn: request span not active across `await`), `@opentelemetry/core` (warn: incoming `traceparent` not joined; installed with the SDK), instrumentations `auto-instrumentations-node`, else `instrumentation-http` / `instrumentation-mongodb` (debug). A tracer provider, context manager or propagator the host registered first (e.g. `NodeSDK`) is kept and used.
|
|
75
|
+
|
|
76
|
+
Request spans are named `{METHOD} {route template}` (`GET /products/:id`), or `{METHOD}` when no route matched; never the raw URL. Attributes are the stable semantic-convention constants: `http.request.method`, `http.route`, `http.response.status_code`, `url.path`, `url.scheme`, `server.address`, `user_agent.original`, and `error.type` on 5xx. The query string is not recorded (it can carry tokens). `traced()` sets `db.operation.name`.
|
|
65
77
|
|
|
66
78
|
```typescript
|
|
67
79
|
import { tracingPlugin, createSpan, traced } from '@classytic/arc/plugins/tracing';
|
|
@@ -43,7 +43,7 @@ import { EventOutbox, MemoryOutboxStore } from '@classytic/arc/events';
|
|
|
43
43
|
const relay = new EventOutbox({ store: new MemoryOutboxStore(), transport, batchSize: 100, failurePolicy });
|
|
44
44
|
// or { repository: new Repository(OutboxModel), transport }
|
|
45
45
|
await relay.store(event, { session });
|
|
46
|
-
await relay.
|
|
46
|
+
await relay.relayBatch(); // publishes pending; returns a RelayResult
|
|
47
47
|
```
|
|
48
48
|
|
|
49
49
|
## Compensating transactions
|
|
@@ -20,13 +20,12 @@ defineResource({
|
|
|
20
20
|
allowedFilterFields: ['status', 'category'],
|
|
21
21
|
allowedSortFields: ['createdAt', 'price'],
|
|
22
22
|
allowedOperators: ['eq', 'gte', 'lte', 'in'],
|
|
23
|
-
strictFilterFields: true, // unknown filter key = 400 instead of dropped
|
|
24
23
|
}),
|
|
25
24
|
schemaOptions: { query: { allowedPopulate: ['category'], allowedLookups: ['categories'] } },
|
|
26
25
|
});
|
|
27
26
|
```
|
|
28
27
|
|
|
29
|
-
- An unknown filter key is
|
|
28
|
+
- An unknown filter key is a 400 by default. Dropping it instead WIDENS the result (200 with every row): mongokit's `QueryParser` drops with `invalidInput: 'drop'`; arc's built-in `ArcQueryParser` with `strictFilterFields: false` or `ARC_STRICT_QUERY_PARAMS=false`.
|
|
30
29
|
- `?limit` above the cap is clamped, not rejected; the cap is in the OpenAPI parameter description.
|
|
31
30
|
- One cap, one owner: parser, repository and arc all cap page size and the lowest wins. Configure the same number everywhere; arc warns at boot on a mismatch.
|
|
32
31
|
- `limit` is `defaultLimit` / `maxLimit` on the resource.
|
|
@@ -24,7 +24,8 @@ export default defineResource({
|
|
|
24
24
|
query: { allowedPopulate: ['category'], filterableFields: { status: { type: 'string' } } },
|
|
25
25
|
},
|
|
26
26
|
cache: { staleTime: 30, gcTime: 300, tags: ['catalog'] },
|
|
27
|
-
routes: [{ method: 'GET', path: '/featured',
|
|
27
|
+
routes: [{ method: 'GET', path: '/featured', permissions: allowPublic(),
|
|
28
|
+
handler: (ctx) => controller.getFeatured(ctx) }],
|
|
28
29
|
actions: { approve: { handler: approve, permissions: requireRoles(['admin']) } },
|
|
29
30
|
});
|
|
30
31
|
```
|
|
@@ -35,11 +36,10 @@ Auto-generated: `GET /`, `GET /:id`, `POST /`, `PATCH /:id`, `DELETE /:id`. Pres
|
|
|
35
36
|
|
|
36
37
|
| Field | Signature | Behaviour |
|
|
37
38
|
|---|---|---|
|
|
38
|
-
| `handler` | `(ctx: IRequestContext)`
|
|
39
|
-
| `rawHandler` | `(request, reply)`
|
|
40
|
-
| `controllerMethod` | `(c: MyController) => c.method` | typed ref, TS catches typos |
|
|
39
|
+
| `handler` | `(ctx: IRequestContext)` | arc pipeline: envelope, field-write permissions, MCP tool. The normal form |
|
|
40
|
+
| `rawHandler` | `(request, reply)` | Fastify-native: owns the response, no pipeline, no MCP unless `mcpHandler`. Streams, raw-body webhooks, files, redirects |
|
|
41
41
|
|
|
42
|
-
Both on one route throws at boot. `streamResponse: true` needs `rawHandler`. Custom endpoints belong in `routes:` / `actions:` (they inherit auth, OpenAPI, MCP); a bare `fastify.get()` bypasses all of it. Declare the schema with `routeInput` (see `references/validation.md`).
|
|
42
|
+
To reach a controller method, call it: `handler: (ctx) => controller.getStats(ctx)`; set `operation` to keep a stable MCP tool and pipeline name. Both on one route throws at boot. `streamResponse: true` needs `rawHandler`. Custom endpoints belong in `routes:` / `actions:` (they inherit auth, OpenAPI, MCP); a bare `fastify.get()` bypasses all of it. Declare the schema with `routeInput` (see `references/validation.md`).
|
|
43
43
|
|
|
44
44
|
Actions share one `POST /:id/action` mount (`id: false` mounts `POST /action`); throttle one by making it a route with `rateLimit`. An action with no permission and no `permissions.update` fallback throws at boot (`allowPublic()` to opt out).
|
|
45
45
|
|
|
@@ -81,6 +81,8 @@ Model constraints win; `fieldRules` supplements what the model lacks.
|
|
|
81
81
|
| `filesUpload` | `POST /upload`, `GET /:id`, `DELETE /:id` | `{ storage, allowedMimeTypes?, maxFileSize? }` |
|
|
82
82
|
| `search` | `POST /search`, `/search-similar`, `/embed` | `{ repository?, search?, similar?, embed? }` |
|
|
83
83
|
|
|
84
|
+
- Preset read routes inherit the CRUD key (`slugLookup`, `filesUpload` read → `get`; `tree`, `search` → `list`); with none they fail boot under `strictPermissions` (`preset-route-public-by-omission`). Public is `allowPublic()`.
|
|
85
|
+
- `multiTenant` guards every route: preset routes get their CRUD route's tenant guard, custom `handler` routes the filter; `tenantScope: true` adds body injection (and covers `rawHandler`), `false` opts out.
|
|
84
86
|
- `tenantField: false` disables the org filter (lookup tables, platform settings).
|
|
85
87
|
- `idField` picks the `:id` lookup column (default `_id`). A 404 on `PATCH` when `GET` works is usually a permission `filters` clause, not `idField`.
|
|
86
88
|
- Presets compose and order matters. A custom `controller` does not receive preset-injected fields: forward `tenantField` / `schemaOptions` / `idField` through `super()` and also pass them to `defineResource`, or extend `BaseController`.
|
|
@@ -90,7 +92,7 @@ Model constraints win; `fieldRules` supplements what the model lacks.
|
|
|
90
92
|
| Behaviour | Default | Switch |
|
|
91
93
|
|---|---|---|
|
|
92
94
|
| non-writable field in body | 403 with the denied list | `onFieldWriteDenied: 'strip'` |
|
|
93
|
-
| write to an `immutable` field |
|
|
95
|
+
| write to an `immutable` field | 403 | `onImmutableWrite: 'strip'` or `ARC_STRICT_IMMUTABLE_WRITES=false` |
|
|
94
96
|
| ungated CRUD write | fatal at define time | `strictPermissions: false` (not recommended) |
|
|
95
97
|
| multiTenant on update | body org overwritten with caller's scope | none |
|
|
96
98
|
|
|
@@ -76,7 +76,7 @@ createHttpTestHarness(productResource, () => ({
|
|
|
76
76
|
})).runAll(); // or runCrud() / runPermissions() / runValidation()
|
|
77
77
|
```
|
|
78
78
|
|
|
79
|
-
Reads the resource config (`
|
|
79
|
+
Reads the resource config (`crud`, `updateMethod`) and probes each enabled route. Pass a getter when the app is built in `beforeAll`.
|
|
80
80
|
|
|
81
81
|
## Fixtures
|
|
82
82
|
|
|
@@ -16,7 +16,7 @@ defineResource({
|
|
|
16
16
|
fields, onFieldWriteDenied, onImmutableWrite,
|
|
17
17
|
tenantField, onTenantDelete, idField, lookupFields, defaultSort, defaultLimit, maxLimit,
|
|
18
18
|
cache, events, audit, history, rateLimit, idempotency, mcp, queryParser,
|
|
19
|
-
|
|
19
|
+
crud, // { list: true, get: true } or false
|
|
20
20
|
strictPermissions, strictSchemas, skipValidation,
|
|
21
21
|
});
|
|
22
22
|
```
|
|
@@ -41,7 +41,7 @@ defineResource({
|
|
|
41
41
|
| target org inside caller's hierarchy | `requireOrgInScope(targetId)` |
|
|
42
42
|
| same gate on all CRUD keys | `permissionMatrix({ read, write, delete? })` |
|
|
43
43
|
| role by resource by action table | `createDynamicPermissionMatrix` |
|
|
44
|
-
| common shapes | `
|
|
44
|
+
| common shapes | `publicReadAdminWrite()`, `publicRead()`, `adminOnly()`, `readOnly()` |
|
|
45
45
|
|
|
46
46
|
## Scope accessors instead of `req.user`
|
|
47
47
|
|
|
@@ -21,8 +21,8 @@ Never redeclare the bags as `Record<string, unknown>`: that forces `as never` at
|
|
|
21
21
|
|
|
22
22
|
| Slot kind | Merge |
|
|
23
23
|
|---|---|
|
|
24
|
-
| top-level arrays (`routes`, `middlewares`, `presets`, `routeGuards
|
|
25
|
-
| plain objects (`permissions`, `actions`, `schemaOptions`, `fieldRules`, `aggregations`, `customSchemas`, `fields`, `cache`, `events`) | recursive per key; nested arrays replace |
|
|
24
|
+
| top-level arrays (`routes`, `middlewares`, `presets`, `routeGuards`) | concat, base first |
|
|
25
|
+
| plain objects (`permissions`, `actions`, `crud`, `schemaOptions`, `fieldRules`, `aggregations`, `customSchemas`, `fields`, `cache`, `events`) | recursive per key; nested arrays replace (`crud: false` is a scalar: last wins) |
|
|
26
26
|
| class instances and scalars (`adapter`, `controller`, `queryParser`) | last wins |
|
|
27
27
|
|
|
28
28
|
```ts
|
|
@@ -1,40 +0,0 @@
|
|
|
1
|
-
/*! @classytic/arc v2.51.0 | MIT | https://classytic.com */
|
|
2
|
-
// src/scope/rateLimitKey.ts
|
|
3
|
-
/**
|
|
4
|
-
* Marks a key generator as SCOPE-AWARE, so `buildRateLimitOpts` can place the rate-limit
|
|
5
|
-
* hook after authentication instead of before it.
|
|
6
|
-
*
|
|
7
|
-
* Without this, the degradation is invisible: `@fastify/rate-limit` runs at `onRequest`,
|
|
8
|
-
* arc authenticates in a `preHandler`, so a scope-keyed generator sees `PUBLIC_SCOPE`,
|
|
9
|
-
* returns the IP for every caller, and — behind a proxy — buckets an entire deployment
|
|
10
|
-
* together. Nothing throws; the limiter simply answers a question nobody asked.
|
|
11
|
-
*
|
|
12
|
-
* `Symbol.for` so the marker survives two copies of arc in one tree.
|
|
13
|
-
*/
|
|
14
|
-
const SCOPE_AWARE_KEY_GENERATOR = Symbol.for("arc.rateLimit.scopeAwareKeyGenerator");
|
|
15
|
-
/** True when this generator needs a resolved scope (see the symbol's docblock). */
|
|
16
|
-
function isScopeAwareKeyGenerator(fn) {
|
|
17
|
-
return typeof fn === "function" && fn[SCOPE_AWARE_KEY_GENERATOR] === true;
|
|
18
|
-
}
|
|
19
|
-
function createTenantKeyGenerator(opts) {
|
|
20
|
-
const generator = opts?.strategy ?? defaultTenantStrategy;
|
|
21
|
-
/**
|
|
22
|
-
* Wrapped rather than tagged in place: a host's `strategy` is its own function, and
|
|
23
|
-
* stamping a symbol onto it would mutate a value it may reuse elsewhere.
|
|
24
|
-
*/
|
|
25
|
-
const tagged = (ctx) => generator(ctx);
|
|
26
|
-
Object.defineProperty(tagged, SCOPE_AWARE_KEY_GENERATOR, {
|
|
27
|
-
value: true,
|
|
28
|
-
enumerable: false
|
|
29
|
-
});
|
|
30
|
-
return tagged;
|
|
31
|
-
}
|
|
32
|
-
function defaultTenantStrategy(ctx) {
|
|
33
|
-
const scope = ctx.scope;
|
|
34
|
-
if (!scope || scope.kind === "public") return ctx.ip;
|
|
35
|
-
if (scope.kind === "member") return scope.organizationId;
|
|
36
|
-
if (scope.kind === "service") return scope.organizationId;
|
|
37
|
-
if (scope.kind === "elevated") return scope.organizationId ?? scope.userId ?? ctx.ip;
|
|
38
|
-
return scope.userId ?? ctx.ip;
|
|
39
|
-
}
|
|
40
|
-
export { isScopeAwareKeyGenerator as n, createTenantKeyGenerator as t };
|