@classytic/arc 2.45.2 → 2.47.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 +1 -1
- package/dist/{EventTransport-DHb1tpu-.mjs → EventTransport-BHKy4_Bi.mjs} +5 -6
- package/dist/{EventTransport-CiicKz2Z.d.mts → EventTransport-CYEoCJGe.d.mts} +0 -2
- package/dist/{HookSystem-C1u0EUnt.mjs → HookSystem-CAIDVoKC.mjs} +3 -4
- package/dist/{QueryCache--5uAuYPW.d.mts → QueryCache-DdvrGG8Q.d.mts} +1 -3
- package/dist/{ResourceRegistry-D2jXWVN_.mjs → ResourceRegistry-23Ml6FNe.mjs} +15 -4
- package/dist/{acquire-DTkA8Lme.mjs → acquire-DoFX06fm.mjs} +2 -3
- package/dist/{actionPermissions-DRVk6m7x.mjs → actionPermissions-DXrlWHHK.mjs} +37 -42
- package/dist/audit/index.d.mts +2 -10
- package/dist/audit/index.mjs +8 -12
- package/dist/auth/audit.d.mts +0 -2
- package/dist/auth/audit.mjs +2 -3
- package/dist/auth/index.d.mts +9 -17
- package/dist/auth/index.mjs +26 -29
- package/dist/auth/redis-session.d.mts +2 -4
- package/dist/auth/redis-session.mjs +2 -3
- package/dist/{authorizationDecision-D48fUJv1.mjs → authorizationDecision-DYiubkYw.mjs} +5 -6
- package/dist/{base-CZyixEQR.d.mts → base-HXNgPQww.d.mts} +1 -7
- package/dist/{boundedMap-DkKiPifd.mjs → boundedMap-CtdzpJ3X.mjs} +2 -3
- package/dist/{buildHandler-BiZ4VATS.mjs → buildHandler-CARdmPNo.mjs} +5 -6
- package/dist/cache/index.d.mts +4 -10
- package/dist/cache/index.mjs +5 -6
- package/dist/{caching-Cj0as-P1.mjs → caching-QRiryDLs.mjs} +3 -4
- package/dist/{claimed-ChI13rUR.mjs → claimed-BLecr1j3.mjs} +2 -3
- package/dist/cleanup/index.d.mts +4 -18
- package/dist/cleanup/index.mjs +12 -20
- package/dist/cli/commands/describe.d.mts +1 -3
- package/dist/cli/commands/describe.mjs +4 -5
- package/dist/cli/commands/docs.d.mts +1 -3
- package/dist/cli/commands/docs.mjs +4 -5
- package/dist/cli/commands/doctor.d.mts +1 -3
- package/dist/cli/commands/doctor.mjs +2 -3
- package/dist/cli/commands/generate.d.mts +1 -1
- package/dist/cli/commands/generate.mjs +2 -2
- package/dist/cli/commands/init.d.mts +1 -1
- package/dist/cli/commands/init.mjs +2 -2
- package/dist/cli/commands/introspect.d.mts +1 -3
- package/dist/cli/commands/introspect.mjs +3 -4
- package/dist/cli/index.d.mts +2 -2
- package/dist/cli/index.mjs +3 -3
- package/dist/{constants-D_aiew34.mjs → constants-Cx7BcnHT.mjs} +2 -3
- package/dist/context/index.d.mts +0 -8
- package/dist/context/index.mjs +6 -7
- package/dist/core/index.d.mts +3 -3
- package/dist/core/index.mjs +8 -8
- package/dist/{core-QIZ2560Y.mjs → core-0WyMuo0f.mjs} +9 -12
- package/dist/{createActionRouter-CvH84dyx.mjs → createActionRouter-mLAGbpDV.mjs} +7 -8
- package/dist/{createAggregationRouter-DGyK2Hp6.mjs → createAggregationRouter-BEAjn3dA.mjs} +9 -10
- package/dist/{createApp-CKjZpmq9.mjs → createApp-QDP4vYWH.mjs} +49 -62
- package/dist/{createMcpServer-DSztofa9.d.mts → createMcpServer-DzXHX0SO.d.mts} +1 -3
- package/dist/{defineAggregation-BLza7Ca4.mjs → defineAggregation-CFNfvz-C.mjs} +2 -3
- package/dist/{defineResource-CEo0gDCb.mjs → defineResource-BROJmhzJ.mjs} +80 -29
- package/dist/discovery/index.d.mts +1 -3
- package/dist/discovery/index.mjs +2 -3
- package/dist/docs/index.d.mts +8 -8
- package/dist/docs/index.mjs +4 -5
- package/dist/{elevation-BW2J3tNj.d.mts → elevation-DPD0hcU-.d.mts} +0 -2
- package/dist/{elevation-BJTsSnke.mjs → elevation-DrXeEWWk.mjs} +9 -10
- package/dist/encryption/index.d.mts +1 -7
- package/dist/encryption/index.mjs +8 -13
- package/dist/{errorHandler--4rSMMvq.d.mts → errorHandler-B9r88jZV.d.mts} +8 -3
- package/dist/{errorHandler-2p4SL5zm.mjs → errorHandler-BiBXtxj4.mjs} +16 -6
- package/dist/{errors-JYc9vwqE.d.mts → errors-DTo0me1o.d.mts} +0 -2
- package/dist/{errors-grZkIA8N.mjs → errors-DnrUChAy.mjs} +2 -3
- package/dist/{eventPlugin-BtmA4-3P.d.mts → eventPlugin-BY38F6yK.d.mts} +1 -7
- package/dist/{eventPlugin-ItcYBGUs.mjs → eventPlugin-BhKLUe7H.mjs} +10 -12
- package/dist/{eventTypes-Ck6fD3ne.mjs → eventTypes-CCIRGakw.mjs} +5 -8
- package/dist/events/index.d.mts +5 -17
- package/dist/events/index.mjs +9 -9
- package/dist/events/transports/redis-stream-entry.d.mts +1 -1
- package/dist/events/transports/redis-stream-entry.mjs +5 -6
- package/dist/events/transports/redis.d.mts +2 -4
- package/dist/events/transports/redis.mjs +3 -4
- package/dist/{externalPaths-CmGOxOtD.d.mts → externalPaths-BOqdq5wr.d.mts} +0 -2
- package/dist/factory/index.d.mts +4 -14
- package/dist/factory/index.mjs +12 -18
- package/dist/{fastify-augmentation-DRlCIWE9.d.mts → fastify-augmentation-bzkWPt1f.d.mts} +4 -10
- package/dist/{fields-BRX0Krcj.mjs → fields-CYdpcV73.mjs} +2 -3
- package/dist/{fields-BBSpf8pS.d.mts → fields-JTkrtO-r.d.mts} +0 -2
- package/dist/{filter-merge-CDc7YMwX.mjs → filter-merge-6kasezRH.mjs} +2 -3
- package/dist/{generate-DCGuEbqI.d.mts → generate-C-g_KOkV.d.mts} +0 -4
- package/dist/{generate-hvg7V2g1.mjs → generate-DUkcbc4r.mjs} +7 -12
- package/dist/{headers-Cqkg4LzI.mjs → headers-KxhrKevA.mjs} +3 -4
- package/dist/{health-PVt0VjOx.mjs → health-CRJg3IIq.mjs} +2 -3
- package/dist/{health-DyeP3mTW.mjs → health-jkYNdobJ.mjs} +4 -7
- package/dist/hooks/index.d.mts +1 -1
- package/dist/hooks/index.mjs +2 -2
- package/dist/http-cache/index.d.mts +211 -0
- package/dist/http-cache/index.mjs +605 -0
- package/dist/http-cache/purgers/cloudflare.d.mts +13 -0
- package/dist/http-cache/purgers/cloudflare.mjs +46 -0
- package/dist/http-cache/purgers/fastly.d.mts +12 -0
- package/dist/http-cache/purgers/fastly.mjs +47 -0
- package/dist/http-cache/testing/index.d.mts +68 -0
- package/dist/http-cache/testing/index.mjs +168 -0
- package/dist/idempotency/index.d.mts +3 -9
- package/dist/idempotency/index.mjs +11 -14
- package/dist/idempotency/redis.d.mts +1 -1
- package/dist/idempotency/redis.mjs +3 -4
- package/dist/{index-Bxriq3so.d.mts → index-B5i9-vuP.d.mts} +4 -26
- package/dist/{index-Chgz3d0i.d.mts → index-BAXDo5eE.d.mts} +1 -7
- package/dist/{index-Beg3aNnK.d.mts → index-BxZS-8So.d.mts} +67 -25
- package/dist/{index-WH7xgvxS.d.mts → index-Cy2-QffW.d.mts} +40 -92
- package/dist/{index-uhkUA5-U.d.mts → index-D1X_C_qz.d.mts} +13 -23
- package/dist/{index-CUJvoyw3.d.mts → index-DFCCQ9AE.d.mts} +2 -24
- package/dist/index.d.mts +7 -9
- package/dist/index.mjs +12 -13
- package/dist/{init-jC3rMPzb.mjs → init-CACwpktI.mjs} +18 -35
- package/dist/{init-Cscs4lab.d.mts → init-CV2_Fw3H.d.mts} +0 -4
- package/dist/integrations/event-gateway.d.mts +3 -5
- package/dist/integrations/event-gateway.mjs +3 -4
- package/dist/integrations/index.d.mts +3 -3
- package/dist/integrations/index.mjs +1 -1
- package/dist/integrations/jobs/index.d.mts +1 -1
- package/dist/integrations/jobs/index.mjs +7 -11
- package/dist/integrations/mcp/index.d.mts +7 -39
- package/dist/integrations/mcp/index.mjs +8 -14
- package/dist/integrations/mcp/testing.d.mts +3 -5
- package/dist/integrations/mcp/testing.mjs +3 -4
- package/dist/integrations/streamline.d.mts +1 -3
- package/dist/integrations/streamline.mjs +4 -5
- package/dist/integrations/webhooks.d.mts +2 -4
- package/dist/integrations/webhooks.mjs +5 -5
- package/dist/integrations/websocket-pushref-redis.d.mts +2 -4
- package/dist/integrations/websocket-pushref-redis.mjs +2 -3
- package/dist/integrations/websocket-redis.d.mts +2 -4
- package/dist/integrations/websocket-redis.mjs +2 -3
- package/dist/integrations/websocket.d.mts +2 -2
- package/dist/integrations/websocket.mjs +13 -24
- package/dist/{interface-JJzwH4Ro.d.mts → interface-BmExzQRD.d.mts} +0 -2
- package/dist/{interface-BOk3YnTz.d.mts → interface-WR1U0K7t.d.mts} +0 -2
- package/dist/{jsonBody-ptwyzZQ-.mjs → jsonBody-CzDBkCme.mjs} +3 -4
- package/dist/{keys-C1vFuSbv.mjs → keys-Cbwf6r1B.mjs} +2 -3
- package/dist/{loadResources-CHPDyIPn.mjs → loadResources-Kr6vuljv.mjs} +4 -5
- package/dist/{loadResourcesFromEntry-BkHHTu_B.mjs → loadResourcesFromEntry-D2e0qoDR.mjs} +3 -4
- package/dist/logger/index.d.mts +1 -3
- package/dist/logger/index.mjs +2 -2
- package/dist/{logger-C5bvCiAK.mjs → logger-C110X5Yz.mjs} +3 -5
- package/dist/{mcpPlugin-C9qohJCF.mjs → mcpPlugin-4lIPr9OJ.mjs} +41 -60
- package/dist/{memory-CxiTwT0j.mjs → memory-D9qkhXiB.mjs} +4 -5
- package/dist/{metrics-Ckp2zRy-.mjs → metrics-B-qrrWfI.mjs} +4 -5
- package/dist/middleware/index.d.mts +1 -5
- package/dist/middleware/index.mjs +4 -5
- package/dist/migrations/index.d.mts +0 -2
- package/dist/migrations/index.mjs +3 -4
- package/dist/{module-CfnKuIuH.mjs → module-BD8xHgrz.mjs} +2 -3
- package/dist/{multiTenant-CAtYlW6H.d.mts → multiTenant-KZj8j1uJ.d.mts} +1 -5
- package/dist/{multipartBody-BFasGtP9.mjs → multipartBody-qU7KCn1l.mjs} +2 -3
- package/dist/observeSend-BnPtTotW.mjs +20 -0
- package/dist/{openapi-DAPxjYHX.mjs → openapi-DoVa5SVP.mjs} +18 -28
- package/dist/outbox-admin/index.d.mts +2 -4
- package/dist/outbox-admin/index.mjs +6 -7
- package/dist/{outbox-module-gZCHoE4H.d.mts → outbox-module-5Mnwcycy.d.mts} +3 -9
- package/dist/outbox-module-DyITEIop.mjs +297 -0
- package/dist/permissions/index.d.mts +4 -4
- package/dist/permissions/index.mjs +7 -7
- package/dist/{permissions-B14c3OMp.mjs → permissions-BBy4bOGi.mjs} +19 -29
- package/dist/{pipe-CQv7PsAK.mjs → pipe-BOm2o4UA.mjs} +3 -4
- package/dist/pipeline/index.d.mts +1 -9
- package/dist/pipeline/index.mjs +5 -8
- package/dist/{plan-CpnTykjb.mjs → plan-DDIGwuxr.mjs} +5 -9
- package/dist/{plugin-DXTjVg_Q.mjs → plugin-Bn4D_0XK.mjs} +156 -64
- package/dist/plugins/index.d.mts +8 -16
- package/dist/plugins/index.mjs +22 -26
- package/dist/plugins/response-cache.d.mts +2 -4
- package/dist/plugins/response-cache.mjs +10 -10
- package/dist/plugins/tracing-entry.d.mts +1 -1
- package/dist/plugins/tracing-entry.mjs +3 -4
- package/dist/{pluralize-C3VJKRGp.mjs → pluralize-ClEjcKlG.mjs} +2 -3
- package/dist/policy.types-DPqToKG1.d.mts +50 -0
- package/dist/presets/filesUpload.d.mts +4 -6
- package/dist/presets/filesUpload.mjs +6 -7
- package/dist/presets/index.d.mts +3 -19
- package/dist/presets/index.mjs +2 -2
- package/dist/presets/multiTenant.d.mts +1 -1
- package/dist/presets/multiTenant.mjs +7 -7
- package/dist/presets/search.d.mts +3 -5
- package/dist/presets/search.mjs +3 -4
- package/dist/{presets-CquqYJPy.mjs → presets-DK2jh5YR.mjs} +11 -18
- package/dist/{projection-CgfSLOSM.mjs → projection-BHH-sXyS.mjs} +3 -4
- package/dist/purger.types-2wNJK_89.mjs +24 -0
- package/dist/purger.types-DvPp4-yd.d.mts +26 -0
- package/dist/{pushref-registry-UxCkoA4C.d.mts → pushref-registry-d86QUaSq.d.mts} +0 -6
- package/dist/{queryCachePlugin-D0HUISHJ.mjs → queryCachePlugin-Ckqe98AM.mjs} +8 -10
- package/dist/{queryCachePlugin-C2lZjTxk.d.mts → queryCachePlugin-DYQUyeJ9.d.mts} +2 -4
- package/dist/{rateLimitKey-AvkBOMkl.mjs → rateLimitKey-CWAjlqcN.mjs} +2 -3
- package/dist/{realtime-CbWtVbqK.mjs → realtime-BIJi9USY.mjs} +17 -19
- package/dist/{redis-BDgv9Glw.d.mts → redis-RpDMemdm.d.mts} +2 -4
- package/dist/{redis-stream-BMk-bpQS.d.mts → redis-stream-CS1N9dwM.d.mts} +1 -3
- package/dist/{redisShapes-CQksY67q.d.mts → redisShapes-CqBXTn_s.d.mts} +0 -2
- package/dist/registry/index.d.mts +2 -12
- package/dist/registry/index.mjs +3 -3
- package/dist/{registry-BVwpAuFI.mjs → registry-y9ZA-R_J.mjs} +7 -12
- package/dist/{outbox-module-B4FAkx3A.mjs → relay-BNrC1CEP.mjs} +8 -306
- package/dist/{renewingLease-CykpeNcQ.mjs → renewingLease-CS43br5E.mjs} +2 -3
- package/dist/{replyHelpers-DA51IZio.mjs → replyHelpers-oZDzakGb.mjs} +3 -4
- package/dist/{requestContext-DIWHKDtQ.mjs → requestContext-fWb_YaV2.mjs} +2 -3
- package/dist/{requirement-Cp_fsMDL.mjs → requirement--2hWyyHi.mjs} +2 -3
- package/dist/{requirement-CbiLdQ1n.d.mts → requirement-CTRQjjQx.d.mts} +0 -2
- package/dist/{resourceRateLimit-BFuluodF.mjs → resourceRateLimit-1WbcyMZY.mjs} +3 -4
- package/dist/{resourceRateLimit-Wf6d6FL9.d.mts → resourceRateLimit-DCWglD7V.d.mts} +1 -3
- package/dist/{rolldown-runtime-D_lMdYOd.mjs → rolldown-runtime-yH2lHMo_.mjs} +2 -3
- package/dist/{routeValidator-DuLonYwr.mjs → routeValidator-BSlRIA5c.mjs} +2 -3
- package/dist/{runtimeCapabilities-CydRfm0i.mjs → runtimeCapabilities-CYCEtU1W.mjs} +2 -3
- package/dist/{schedules-B693KXxa.mjs → schedules-B5WGlYIT.mjs} +132 -9
- package/dist/{schemaConverter-DNvZWTV6.mjs → schemaConverter-DtNvts-6.mjs} +3 -4
- package/dist/{schemaIR-REV2y7Wd.mjs → schemaIR-uS_RHqa3.mjs} +3 -4
- package/dist/schemas/index.d.mts +0 -2
- package/dist/schemas/index.mjs +2 -3
- package/dist/scim/index.d.mts +0 -12
- package/dist/scim/index.mjs +10 -18
- package/dist/scope/index.d.mts +2 -6
- package/dist/scope/index.mjs +5 -5
- package/dist/{scope-Bevxy_ST.mjs → scope-BwVLSyNG.mjs} +5 -6
- package/dist/{sessionManager-qimlKV0P.d.mts → sessionManager-CdvDF04x.d.mts} +2 -4
- package/dist/{shutdown-CfrqPR7A.mjs → shutdown-BJiJN7FT.mjs} +2 -3
- package/dist/{simpleEqualityMatcher-BJwfuRKP.mjs → simpleEqualityMatcher-DGRLq-1k.mjs} +2 -3
- package/dist/{sse-CuNNWr2z.mjs → sse-B_50llZu.mjs} +8 -9
- package/dist/{sseStream-C_2ujAVY.mjs → sseStream-BjSo9Ult.mjs} +3 -4
- package/dist/{storage-Cx9Sz3Ou.d.mts → storage-odC5MNKN.d.mts} +0 -2
- package/dist/{store-helpers-C8uBGCbb.mjs → store-helpers-D-n5cwy5.mjs} +2 -3
- package/dist/{streaming-Bdq_M4d5.mjs → streaming-Dcgqa-hH.mjs} +2 -3
- package/dist/{subscriberIdentity-B-KpZkdl.mjs → subscriberIdentity-C9KhIXTF.mjs} +2 -3
- package/dist/{tenancy-C5PCvm1h.mjs → tenancy-COrhjPRZ.mjs} +3 -4
- package/dist/{tenantPreparation-dYvWrgNa.mjs → tenantPreparation-BElWHytd.mjs} +5 -6
- package/dist/testing/cleanupStoreContract.d.mts +2 -4
- package/dist/testing/cleanupStoreContract.mjs +2 -3
- package/dist/testing/index.d.mts +6 -32
- package/dist/testing/index.mjs +24 -37
- package/dist/testing/outboxStoreContract.d.mts +1 -3
- package/dist/testing/outboxStoreContract.mjs +3 -4
- package/dist/testing/requiredPorts.d.mts +2 -4
- package/dist/testing/requiredPorts.mjs +3 -4
- package/dist/testing/storageContract.d.mts +2 -4
- package/dist/testing/storageContract.mjs +2 -3
- package/dist/{timing-DCqsezX8.mjs → timing-CaxKbRk_.mjs} +3 -5
- package/dist/{tracing-Dro5eH6j.d.mts → tracing-JSFiBl5r.d.mts} +0 -2
- package/dist/{transactionContext-DrcNyjpv.mjs → transactionContext-8qKON0Nk.mjs} +2 -3
- package/dist/{typeGuards-CEl10KPy.mjs → typeGuards-DVjVSsXO.mjs} +2 -3
- package/dist/types/index.d.mts +4 -4
- package/dist/types/index.mjs +1 -1
- package/dist/types/storage.d.mts +1 -1
- package/dist/types/storage.mjs +1 -1
- package/dist/{types-ByHn9rEO.d.mts → types-0Dqlbgn8.d.mts} +0 -2
- package/dist/{types-BJ-2XqVF.d.mts → types-BeEJm-DV.d.mts} +114 -14
- package/dist/{types-DVLddu2q.d.mts → types-C0YJAiL0.d.mts} +0 -2
- package/dist/{types-D9NWjpYc.mjs → types-DZHqOuJE.mjs} +5 -6
- package/dist/{types-D3Ixsh00.d.mts → types-DeLiuaNv.d.mts} +2 -4
- package/dist/{types-Ddl9OjmE.d.mts → types-DnkIALZ8.d.mts} +0 -4
- package/dist/usage/index.d.mts +2 -10
- package/dist/usage/index.mjs +8 -12
- package/dist/{userHelpers-BHig1kHq.mjs → userHelpers-_eGj6kf0.mjs} +2 -3
- package/dist/utils/index.d.mts +5 -39
- package/dist/utils/index.mjs +12 -12
- package/dist/{utils-BG5P7_Vb.mjs → utils-Dd6MWpye.mjs} +20 -30
- package/dist/{validate-D_mdOCir.mjs → validate-BaF5wd0x.mjs} +5 -7
- package/dist/{versioning-DBGHjPh7.mjs → versioning-DyV7mwtK.mjs} +4 -5
- package/dist/{versioning-Bqm_57Qt.d.mts → versioning-S18y2-0C.d.mts} +1 -15
- package/dist/{websocket-Cs4awVyD.d.mts → websocket-BGuc-WVZ.d.mts} +1 -15
- package/dist/{workScope-DPPfM4m6.mjs → workScope-CmCBUmPR.mjs} +3 -4
- package/llms.txt +37 -30
- package/package.json +51 -22
- package/skills/arc/SKILL.md +65 -844
- package/skills/arc/references/agent-auth.md +82 -193
- package/skills/arc/references/api-reference.md +41 -245
- package/skills/arc/references/auth-api-keys.md +99 -0
- package/skills/arc/references/auth-better-auth-overlay.md +87 -0
- package/skills/arc/references/auth-better-auth.md +78 -0
- package/skills/arc/references/auth-permissions.md +100 -0
- package/skills/arc/references/auth-strategies.md +122 -0
- package/skills/arc/references/boot.md +80 -0
- package/skills/arc/references/enterprise-auth.md +65 -81
- package/skills/arc/references/events-outbox.md +90 -0
- package/skills/arc/references/events.md +75 -440
- package/skills/arc/references/integrations-jobs.md +74 -0
- package/skills/arc/references/integrations-realtime.md +84 -0
- package/skills/arc/references/integrations-webhooks.md +71 -0
- package/skills/arc/references/integrations-workflows.md +47 -0
- package/skills/arc/references/mcp-auth.md +83 -0
- package/skills/arc/references/mcp-custom-tools.md +125 -0
- package/skills/arc/references/mcp-setup.md +115 -0
- package/skills/arc/references/mcp-testing.md +63 -0
- package/skills/arc/references/multi-tenancy.md +56 -230
- package/skills/arc/references/permissions-scope.md +81 -0
- package/skills/arc/references/production-api.md +119 -0
- package/skills/arc/references/production-audit.md +101 -0
- package/skills/arc/references/production-boot.md +91 -0
- package/skills/arc/references/production-caching.md +63 -0
- package/skills/arc/references/production-distributed.md +75 -0
- package/skills/arc/references/production-idempotency.md +83 -0
- package/skills/arc/references/production-observability.md +83 -0
- package/skills/arc/references/production-realtime.md +70 -0
- package/skills/arc/references/production-reliability.md +100 -0
- package/skills/arc/references/production-shutdown.md +43 -0
- package/skills/arc/references/querying.md +76 -0
- package/skills/arc/references/resources.md +97 -0
- package/skills/arc/references/schedules.md +79 -0
- package/skills/arc/references/scim.md +61 -208
- package/skills/arc/references/tenancy-scope-install.md +82 -0
- package/skills/arc/references/testing.md +101 -144
- package/skills/arc/references/usage-cleanup-capabilities.md +45 -0
- package/skills/arc/references/validation.md +91 -0
- package/skills/arc/references/writes-hooks-errors.md +80 -0
- package/skills/arc-code-review/SKILL.md +67 -114
- package/skills/arc-code-review/references/arc-cheatsheet.md +68 -167
- package/skills/arc-code-review/references/mongokit-repositories.md +104 -0
- package/skills/arc-code-review/references/recipe-events-cache-jobs.md +112 -0
- package/skills/arc-code-review/references/recipe-resource.md +100 -0
- package/skills/arc-code-review/references/recipe-schemas-fields.md +93 -0
- package/skills/arc-code-review/references/recipe-scope-permissions.md +82 -0
- package/skills/arc-code-review/references/scaffolding.md +61 -198
- package/skills/arc-code-review/references/severity.md +49 -102
- package/skills/arc-code-review/references/smells-auth-scope.md +80 -0
- package/skills/arc-code-review/references/smells-data-events.md +66 -0
- package/skills/arc-code-review/references/smells-imports-style.md +59 -0
- package/skills/arc-code-review/references/smells-platform.md +89 -0
- package/skills/arc-code-review/references/smells-routes-schemas.md +66 -0
- package/skills/arc-module-publishing/SKILL.md +82 -208
- package/skills/arc-module-publishing/references/action-presets-and-plugins.md +87 -0
- package/skills/arc-module-publishing/references/build-and-types.md +73 -0
- package/skills/arc-module-publishing/references/module-lifecycle.md +101 -0
- package/skills/arc-module-publishing/references/package-manifest.md +34 -122
- package/skills/arc-module-publishing/references/publishing-workflow.md +44 -140
- package/skills/arc-module-publishing/references/resource-assembly.md +102 -0
- package/skills/arc-module-publishing/references/testing-packages.md +82 -0
- package/skills/arc/references/auth.md +0 -729
- package/skills/arc/references/integrations.md +0 -452
- package/skills/arc/references/mcp.md +0 -691
- package/skills/arc/references/production.md +0 -835
- package/skills/arc-code-review/references/anti-patterns.md +0 -1008
- package/skills/arc-code-review/references/migration-recipes.md +0 -649
- package/skills/arc-code-review/references/mongokit-migration.md +0 -360
- package/skills/arc-module-publishing/references/authoring-modules.md +0 -327
|
@@ -1,835 +0,0 @@
|
|
|
1
|
-
# Arc Production Features
|
|
2
|
-
|
|
3
|
-
Health checks, audit trail, idempotency, tracing, SSE, caching, graceful shutdown.
|
|
4
|
-
|
|
5
|
-
## v2.9 Security Defaults
|
|
6
|
-
|
|
7
|
-
- **Field-write perms reject by default** — `defineResource({ fields, onFieldWriteDenied })`. Default `'reject'` → 403 with denied field list. Legacy silent-strip: `onFieldWriteDenied: 'strip'`.
|
|
8
|
-
- **Elevation always emits `arc.scope.elevated`** — subscribe via `fastify.events.subscribe('arc.scope.elevated', handler)` for audit. `onElevation` callback still supported.
|
|
9
|
-
- **multiTenant injects org on UPDATE** — closes cross-tenant hop vector. Body-supplied `organizationId` overwritten with caller's scope.
|
|
10
|
-
- **`verifySignature(body, secret, sig)` throws TypeError** if body isn't string/Buffer — register `@fastify/raw-body` before webhook routes; pass `req.rawBody`.
|
|
11
|
-
- **Upload `sanitizeFilename` (preset)** — strict by default; `false` / `'*'` / custom fn to relax per adapter needs.
|
|
12
|
-
- **Idempotency `namespace`** — fold an env key into the fingerprint when multiple deployments share a Redis (prod + canary, api + jobs).
|
|
13
|
-
|
|
14
|
-
## Health Plugin
|
|
15
|
-
|
|
16
|
-
Kubernetes-ready liveness/readiness probes:
|
|
17
|
-
|
|
18
|
-
```typescript
|
|
19
|
-
import { healthPlugin } from '@classytic/arc/plugins';
|
|
20
|
-
|
|
21
|
-
await fastify.register(healthPlugin, {
|
|
22
|
-
prefix: '/_health',
|
|
23
|
-
version: '1.0.0',
|
|
24
|
-
checks: [
|
|
25
|
-
{ name: 'mongodb', check: () => mongoose.connection.readyState === 1, critical: true },
|
|
26
|
-
{ name: 'redis', check: async () => await redis.ping() === 'PONG', timeout: 3000 },
|
|
27
|
-
],
|
|
28
|
-
});
|
|
29
|
-
|
|
30
|
-
// GET /_health/live → { status: 'ok', timestamp, version }
|
|
31
|
-
// GET /_health/ready → { status: 'ok', checks: { mongodb: { status: 'ok', latency: 5 } } }
|
|
32
|
-
// Returns 503 if critical check fails
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
## Request ID Plugin
|
|
36
|
-
|
|
37
|
-
```typescript
|
|
38
|
-
import { requestIdPlugin } from '@classytic/arc/plugins';
|
|
39
|
-
|
|
40
|
-
await fastify.register(requestIdPlugin, {
|
|
41
|
-
header: 'x-request-id',
|
|
42
|
-
setResponseHeader: true,
|
|
43
|
-
generator: () => crypto.randomUUID(),
|
|
44
|
-
});
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
## Graceful Shutdown Plugin
|
|
48
|
-
|
|
49
|
-
Registered by default (`arcPlugins.gracefulShutdown`). Pass an options object to configure it inline from `createApp`.
|
|
50
|
-
|
|
51
|
-
```typescript
|
|
52
|
-
import { gracefulShutdownPlugin } from '@classytic/arc/plugins';
|
|
53
|
-
|
|
54
|
-
await fastify.register(gracefulShutdownPlugin, {
|
|
55
|
-
timeout: 30000, // hard cap; drainDelayMs counts against it
|
|
56
|
-
drainDelayMs: 10000, // lame-duck window — see below
|
|
57
|
-
signals: ['SIGTERM', 'SIGINT'],
|
|
58
|
-
logEvents: true,
|
|
59
|
-
onShutdown: async () => {
|
|
60
|
-
await mongoose.disconnect();
|
|
61
|
-
await redis.quit();
|
|
62
|
-
},
|
|
63
|
-
onForceExit: () => {}, // tests: stop a timeout from killing the runner
|
|
64
|
-
});
|
|
65
|
-
|
|
66
|
-
// Sequence: signal → shutdownState.draining = true (/ready starts 503ing)
|
|
67
|
-
// → wait drainDelayMs (still serving) → fastify.close() (stops accepting,
|
|
68
|
-
// drains in-flight) → onShutdown() → exit naturally
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
**`fastify.close()` runs BEFORE `onShutdown`** — so `onShutdown` is where you release what arc doesn't own (DB connections, your own Redis client), and it runs after in-flight requests are done. Don't close anything a request might still need.
|
|
72
|
-
|
|
73
|
-
### `drainDelayMs` — the rolling-deploy 502
|
|
74
|
-
|
|
75
|
-
Default `0`, which is the pre-2.41 behaviour: close the moment SIGTERM arrives. That is the classic rolling-deploy 502 — a load balancer keeps routing to an instance until its readiness probe has failed **for several intervals**, and by then the instance already stopped accepting.
|
|
76
|
-
|
|
77
|
-
`drainDelayMs` is the window between "start failing readiness" and "stop accepting":
|
|
78
|
-
|
|
79
|
-
- `/_health/ready` → `503 { status: 'draining' }` immediately on signal
|
|
80
|
-
- `/_health/live` → stays `200` (a draining process is alive — that's the point; a 503 here gets the pod **killed**, not drained)
|
|
81
|
-
- everything already routed here is still served for the whole window
|
|
82
|
-
|
|
83
|
-
Set it **above** your LB's deregistration window — typically 5000–15000ms. On Kubernetes, also keep `terminationGracePeriodSeconds` > `drainDelayMs + timeout`, or the kubelet SIGKILLs you mid-drain.
|
|
84
|
-
|
|
85
|
-
```typescript
|
|
86
|
-
createApp({
|
|
87
|
-
arcPlugins: { gracefulShutdown: { drainDelayMs: 10_000, timeout: 30_000 } },
|
|
88
|
-
});
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
**Do not also write `process.on('SIGTERM', () => app.close())`.** The plugin already owns those signals; a second handler closes the server immediately and skips the drain entirely — you get the 502s back while the config says you fixed them.
|
|
92
|
-
|
|
93
|
-
## Audit Plugin
|
|
94
|
-
|
|
95
|
-
Change tracking. Pass a `RepositoryLike` for persistence, or omit for in-memory dev:
|
|
96
|
-
|
|
97
|
-
```typescript
|
|
98
|
-
import { auditPlugin } from '@classytic/arc/audit';
|
|
99
|
-
import { Repository } from '@classytic/mongokit';
|
|
100
|
-
|
|
101
|
-
// Development (in-memory)
|
|
102
|
-
await fastify.register(auditPlugin, { enabled: true });
|
|
103
|
-
|
|
104
|
-
// Production — any kit (mongokit / prismakit / custom)
|
|
105
|
-
await fastify.register(auditPlugin, {
|
|
106
|
-
enabled: true,
|
|
107
|
-
repository: new Repository(AuditModel),
|
|
108
|
-
});
|
|
109
|
-
// ── Retention (audit rows ARE `history: true` timelines — prune together) ──
|
|
110
|
-
// Option A (zero code, Mongo): TTL index — the DB does it server-side.
|
|
111
|
-
// AuditSchema.index({ timestamp: 1 }, { expireAfterSeconds: 60 * 60 * 24 * 365 });
|
|
112
|
-
// Option B (built-in, single instance): retention: { maxAgeMs, purgeIntervalMs }.
|
|
113
|
-
// Option C (multi-replica, RECOMMENDED): purgeIntervalMs: 0 + a schedulesPlugin
|
|
114
|
-
// entry calling fastify.audit.purge(cutoff) — leader-safe, jittered, observable.
|
|
115
|
-
// (The built-in timer runs on EVERY replica — idempotent but wasteful.)
|
|
116
|
-
//
|
|
117
|
-
// ── Indexes (kit territory — the audit model is yours) ──
|
|
118
|
-
// Mongo: TTL index above + compound for the history timeline:
|
|
119
|
-
// AuditSchema.index({ resource: 1, documentId: 1, timestamp: -1 });
|
|
120
|
-
// SQL kits: index (resource, document_id, timestamp) + the kit's ttl/sweep plugin.
|
|
121
|
-
//
|
|
122
|
-
// ── Rich search (admin audit-log UI) ──
|
|
123
|
-
// audit.query() is deliberately narrow. For full repo-core filter/sort/keyset
|
|
124
|
-
// power + MCP tools, mount the audit repo AS a read-only resource:
|
|
125
|
-
// defineResource({ name: 'audit-log', crud: { list: true, get: true },
|
|
126
|
-
// adapter: { repository: auditRepo },
|
|
127
|
-
// queryParser: new QueryParser({ allowedFilterFields: ['resource','documentId','userId','action','organizationId'] }),
|
|
128
|
-
// permissions: { list: requireRoles(['auditor']), get: requireRoles(['auditor']) } });
|
|
129
|
-
|
|
130
|
-
// Usage
|
|
131
|
-
await fastify.audit.create('product', product._id, product, request.auditContext);
|
|
132
|
-
await fastify.audit.update('product', id, beforeDoc, afterDoc, request.auditContext);
|
|
133
|
-
await fastify.audit.delete('product', id, deletedDoc, request.auditContext);
|
|
134
|
-
await fastify.audit.custom('product', id, 'price_changed', { oldPrice: 100, newPrice: 150 }, ctx);
|
|
135
|
-
|
|
136
|
-
// Query
|
|
137
|
-
const entries = await fastify.audit.query({
|
|
138
|
-
resource: 'product', documentId: 'prod-123',
|
|
139
|
-
action: 'update', from: new Date('2024-01-01'), limit: 100,
|
|
140
|
-
});
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
**Audit entry:**
|
|
144
|
-
|
|
145
|
-
```typescript
|
|
146
|
-
interface AuditEntry {
|
|
147
|
-
id: string; timestamp: Date;
|
|
148
|
-
action: 'create' | 'update' | 'delete' | 'restore' | 'custom';
|
|
149
|
-
resource: string; documentId: string;
|
|
150
|
-
before?: Record<string, unknown>;
|
|
151
|
-
after?: Record<string, unknown>;
|
|
152
|
-
metadata?: Record<string, unknown>;
|
|
153
|
-
context: { user?; organizationId?; requestId?; ipAddress?; userAgent?; };
|
|
154
|
-
}
|
|
155
|
-
```
|
|
156
|
-
|
|
157
|
-
**Custom store:** Implement `AuditStore` interface (`log`, `query`, `close`).
|
|
158
|
-
|
|
159
|
-
## Idempotency Plugin
|
|
160
|
-
|
|
161
|
-
Exactly-once semantics for mutating operations:
|
|
162
|
-
|
|
163
|
-
```typescript
|
|
164
|
-
import { idempotencyPlugin } from '@classytic/arc/idempotency';
|
|
165
|
-
|
|
166
|
-
await fastify.register(idempotencyPlugin, {
|
|
167
|
-
enabled: true,
|
|
168
|
-
headerName: 'idempotency-key', // Default
|
|
169
|
-
ttlMs: 86400000, // 24 hours
|
|
170
|
-
lockTimeoutMs: 30000,
|
|
171
|
-
methods: ['POST', 'PUT', 'PATCH'],
|
|
172
|
-
include: [/\/orders/], // Only these routes
|
|
173
|
-
exclude: [/\/health/],
|
|
174
|
-
retryAfterSeconds: 1,
|
|
175
|
-
});
|
|
176
|
-
```
|
|
177
|
-
|
|
178
|
-
**Client:**
|
|
179
|
-
|
|
180
|
-
```typescript
|
|
181
|
-
fetch('/api/orders', {
|
|
182
|
-
method: 'POST',
|
|
183
|
-
headers: { 'Idempotency-Key': 'order-abc123-uuid' },
|
|
184
|
-
body: JSON.stringify({ items: [...] }),
|
|
185
|
-
});
|
|
186
|
-
// First request: processes, caches response
|
|
187
|
-
// Retry: returns cached response + x-idempotency-replayed: true
|
|
188
|
-
// Concurrent: returns 409 Conflict + Retry-After: 1
|
|
189
|
-
```
|
|
190
|
-
|
|
191
|
-
**Storage backends:**
|
|
192
|
-
|
|
193
|
-
```typescript
|
|
194
|
-
// Memory (default, dev) — omit both `repository` and `store`
|
|
195
|
-
import { MemoryIdempotencyStore } from '@classytic/arc/idempotency';
|
|
196
|
-
|
|
197
|
-
// Redis (production, multi-instance)
|
|
198
|
-
import { RedisIdempotencyStore } from '@classytic/arc/idempotency/redis';
|
|
199
|
-
store: new RedisIdempotencyStore({ client: redis, prefix: 'idem:', ttlMs: 86400000 })
|
|
200
|
-
|
|
201
|
-
// DB-backed via RepositoryLike (mongokit / prismakit / custom)
|
|
202
|
-
import { Repository, methodRegistryPlugin, batchOperationsPlugin, mongoOperationsPlugin } from '@classytic/mongokit';
|
|
203
|
-
repository: new Repository(IdempotencyModel, [
|
|
204
|
-
methodRegistryPlugin(), batchOperationsPlugin(), mongoOperationsPlugin(),
|
|
205
|
-
])
|
|
206
|
-
```
|
|
207
|
-
|
|
208
|
-
**IdempotencyStore interface:**
|
|
209
|
-
|
|
210
|
-
```typescript
|
|
211
|
-
interface IdempotencyStore {
|
|
212
|
-
readonly name: string;
|
|
213
|
-
get(key: string): Promise<IdempotencyResult | undefined>;
|
|
214
|
-
set(key: string, result): Promise<void>;
|
|
215
|
-
tryLock(key: string, requestId: string, ttlMs: number): Promise<boolean>;
|
|
216
|
-
unlock(key: string, requestId: string): Promise<void>;
|
|
217
|
-
isLocked(key: string): Promise<boolean>;
|
|
218
|
-
delete(key: string): Promise<void>;
|
|
219
|
-
close?(): Promise<void>;
|
|
220
|
-
}
|
|
221
|
-
```
|
|
222
|
-
|
|
223
|
-
## OpenTelemetry Tracing
|
|
224
|
-
|
|
225
|
-
```typescript
|
|
226
|
-
import { tracingPlugin } from '@classytic/arc/plugins/tracing';
|
|
227
|
-
|
|
228
|
-
await fastify.register(tracingPlugin, {
|
|
229
|
-
serviceName: 'my-api',
|
|
230
|
-
exporterUrl: 'http://localhost:4318/v1/traces',
|
|
231
|
-
sampleRate: 0.1, // Trace 10% of requests
|
|
232
|
-
});
|
|
233
|
-
|
|
234
|
-
// Custom spans
|
|
235
|
-
import { createSpan } from '@classytic/arc/plugins/tracing';
|
|
236
|
-
|
|
237
|
-
return createSpan(req, 'processPayment', async (span) => {
|
|
238
|
-
span.setAttribute('orderId', order._id);
|
|
239
|
-
return await processPayment(order);
|
|
240
|
-
});
|
|
241
|
-
```
|
|
242
|
-
|
|
243
|
-
## QueryCache (Server Cache)
|
|
244
|
-
|
|
245
|
-
TanStack Query-inspired server cache with stale-while-revalidate and auto-invalidation on mutations.
|
|
246
|
-
|
|
247
|
-
```typescript
|
|
248
|
-
// Enable globally
|
|
249
|
-
const app = await createApp({
|
|
250
|
-
arcPlugins: { queryCache: true }, // Memory store, zero config
|
|
251
|
-
});
|
|
252
|
-
|
|
253
|
-
// Per-resource config
|
|
254
|
-
defineResource({
|
|
255
|
-
name: 'product',
|
|
256
|
-
cache: {
|
|
257
|
-
staleTime: 30, // seconds fresh (no revalidation)
|
|
258
|
-
gcTime: 300, // seconds stale data kept (SWR window)
|
|
259
|
-
tags: ['catalog'], // cross-resource grouping
|
|
260
|
-
invalidateOn: { 'category.*': ['catalog'] }, // event → tag invalidation
|
|
261
|
-
},
|
|
262
|
-
});
|
|
263
|
-
```
|
|
264
|
-
|
|
265
|
-
**How it works:**
|
|
266
|
-
- `GET` → cached with `x-cache: HIT | STALE | MISS` header
|
|
267
|
-
- `POST/PATCH/DELETE` → auto-bumps resource version, invalidating cached queries
|
|
268
|
-
- Cross-resource: category mutation bumps `catalog` tag → products cache invalidated
|
|
269
|
-
- Multi-tenant safe: cache keys scoped by userId + orgId
|
|
270
|
-
|
|
271
|
-
**Runtime modes:**
|
|
272
|
-
|
|
273
|
-
| Mode | Store | Config |
|
|
274
|
-
|------|-------|--------|
|
|
275
|
-
| `memory` (default) | `MemoryCacheStore` (50 MiB budget) | Zero config |
|
|
276
|
-
| `distributed` | `RedisCacheStore` | `stores: { queryCache: new RedisCacheStore({ client: redis }) }` |
|
|
277
|
-
|
|
278
|
-
## Response Cache Plugin
|
|
279
|
-
|
|
280
|
-
```typescript
|
|
281
|
-
import { responseCachePlugin } from '@classytic/arc/plugins/response-cache';
|
|
282
|
-
|
|
283
|
-
await fastify.register(responseCachePlugin, {
|
|
284
|
-
// ETag generation + Cache-Control headers per route
|
|
285
|
-
});
|
|
286
|
-
```
|
|
287
|
-
|
|
288
|
-
**Note:** When QueryCache is active for a resource, response-cache is automatically skipped for that resource's GET routes.
|
|
289
|
-
|
|
290
|
-
## SSE Plugin (Server-Sent Events)
|
|
291
|
-
|
|
292
|
-
Bridges Arc domain events to SSE streams. Requires `eventPlugin` (auto-registered by factory).
|
|
293
|
-
|
|
294
|
-
```typescript
|
|
295
|
-
// Via factory (recommended)
|
|
296
|
-
const app = await createApp({
|
|
297
|
-
arcPlugins: {
|
|
298
|
-
sse: {
|
|
299
|
-
path: '/events/stream', // SSE endpoint (default: '/events/stream')
|
|
300
|
-
requireAuth: true, // Fail-closed auth (default: true)
|
|
301
|
-
patterns: ['order.*', 'product.*'], // Event patterns to stream (default: ['*'])
|
|
302
|
-
// orgScoped defaults to TRUE (2.41.1) — a caller only sees its own org's events.
|
|
303
|
-
heartbeat: 30000, // Heartbeat interval in ms (default: 30000)
|
|
304
|
-
},
|
|
305
|
-
},
|
|
306
|
-
});
|
|
307
|
-
|
|
308
|
-
// Manual registration
|
|
309
|
-
import { ssePlugin } from '@classytic/arc/plugins';
|
|
310
|
-
await fastify.register(ssePlugin, { requireAuth: true });
|
|
311
|
-
```
|
|
312
|
-
|
|
313
|
-
### Realtime resource change feed (2.22)
|
|
314
|
-
|
|
315
|
-
`arcPlugins: { realtime: true }` → `GET /realtime/:resource` (resource NAME) and
|
|
316
|
-
multiplexed `GET /realtime?resources=a,b,c` (cap 20): SSE change feed gated by the
|
|
317
|
-
resource's own `list` permission with per-event row filtering, tenant guard, and
|
|
318
|
-
field masking. Client = plain `EventSource` with `?token=`. No replay — reconnect
|
|
319
|
-
refetches the list. Choosing: per-user resource views → realtime; bidirectional/geo
|
|
320
|
-
→ `integrations/websocket` (its CRUD bridge is org-coarse — never expose
|
|
321
|
-
row-permissioned resources through it); event firehose → sse. Massive fan-out
|
|
322
|
-
(viral feeds, live scores) → publish once to a dedicated edge fan-out layer
|
|
323
|
-
via `app.events.subscribe(...)`; full tiering guide: docs/production-ops/realtime.mdx.
|
|
324
|
-
|
|
325
|
-
**Fail-closed auth:** When `requireAuth: true` (default), throws at registration if `fastify.authenticate` is missing — prevents exposing SSE without auth.
|
|
326
|
-
|
|
327
|
-
**Org-scoped by default (2.41.1):** an event carrying `organizationId` reaches only callers in that org. It defaulted to `false` — with `patterns: ['*']`, one tenant's member received every tenant's events, full documents included. Events with no `organizationId` still reach everyone, so single-tenant apps are unaffected; an elevated admin with no active org sees all tenants (the platform view). `orgScoped: false` is for a deliberately cross-tenant stream only — keep `requireAuth` and add a `filter`.
|
|
328
|
-
|
|
329
|
-
## Error Handler Plugin
|
|
330
|
-
|
|
331
|
-
```typescript
|
|
332
|
-
import { errorHandlerPlugin } from '@classytic/arc/plugins';
|
|
333
|
-
|
|
334
|
-
// Global error handling — catches all errors, logs, formats response
|
|
335
|
-
// Auto-registered by createApp()
|
|
336
|
-
```
|
|
337
|
-
|
|
338
|
-
### Error Mappers (v2.7.3)
|
|
339
|
-
|
|
340
|
-
Class-based domain error → HTTP response mapping. Register once, handlers just throw:
|
|
341
|
-
|
|
342
|
-
```typescript
|
|
343
|
-
class AccountingError extends Error {
|
|
344
|
-
constructor(message: string, public status: number, public code: string) { super(message); }
|
|
345
|
-
}
|
|
346
|
-
|
|
347
|
-
const app = await createApp({
|
|
348
|
-
errorHandler: {
|
|
349
|
-
errorMappers: [{
|
|
350
|
-
type: AccountingError,
|
|
351
|
-
toResponse: (err) => ({ status: err.status, code: err.code, message: err.message }),
|
|
352
|
-
}],
|
|
353
|
-
},
|
|
354
|
-
});
|
|
355
|
-
// Now handlers just throw — Arc catches and maps automatically
|
|
356
|
-
```
|
|
357
|
-
|
|
358
|
-
Mappers are checked via `instanceof` before all other error classification. Multiple mappers supported — first match wins.
|
|
359
|
-
|
|
360
|
-
## Reply Helpers
|
|
361
|
-
|
|
362
|
-
Opt-in `sendList` + `stream` decorators: `createApp({ replyHelpers: true })`. Arc emits raw data on success — no `{ success, data }` envelope; HTTP status discriminates — so single-doc handlers just `return doc` (or `reply.send(doc)`) and errors throw `ArcError` (the global handler serialises to `ErrorContract`). The two decorators below cover the cases that DO need framework support:
|
|
363
|
-
|
|
364
|
-
```typescript
|
|
365
|
-
// List response — any kit-shaped paginated result OR a bare array → canonical wire shape
|
|
366
|
-
return reply.sendList({ method: 'offset', data, total, page, limit, pages, hasNext, hasPrev });
|
|
367
|
-
return reply.sendList(rows); // bare array endpoints
|
|
368
|
-
```
|
|
369
|
-
|
|
370
|
-
### Streaming Responses
|
|
371
|
-
|
|
372
|
-
```typescript
|
|
373
|
-
// CSV export
|
|
374
|
-
return reply.stream(csvReadableStream, { contentType: 'text/csv', filename: 'export.csv' });
|
|
375
|
-
// PDF download
|
|
376
|
-
return reply.stream(pdfBuffer, { contentType: 'application/pdf', filename: 'report.pdf' });
|
|
377
|
-
// Raw stream (Fastify native — works without reply helpers too)
|
|
378
|
-
return reply.header('content-type', 'text/csv').send(readableStream);
|
|
379
|
-
```
|
|
380
|
-
|
|
381
|
-
### BigInt Serialization
|
|
382
|
-
|
|
383
|
-
Opt-in: `createApp({ serializeBigInt: 'string' })` — BigInt → decimal string in JSON responses (lossless); `'number'` is lossy above 2^53-1.
|
|
384
|
-
|
|
385
|
-
## Multipart Body Middleware (v2.7.3)
|
|
386
|
-
|
|
387
|
-
Opt-in file upload support for CRUD routes — parses multipart form fields into `req.body`, attaches files to `req.body._files`:
|
|
388
|
-
|
|
389
|
-
```typescript
|
|
390
|
-
import { multipartBody } from '@classytic/arc/middleware';
|
|
391
|
-
|
|
392
|
-
defineResource({
|
|
393
|
-
middlewares: { create: [multipartBody({ allowedMimeTypes: ['image/png'], maxFileSize: 5_000_000 })] },
|
|
394
|
-
hooks: {
|
|
395
|
-
'before:create': async (data) => {
|
|
396
|
-
if (data._files?.image) { data.imageUrl = await uploadToS3(data._files.image); delete data._files; }
|
|
397
|
-
return data;
|
|
398
|
-
},
|
|
399
|
-
},
|
|
400
|
-
});
|
|
401
|
-
```
|
|
402
|
-
|
|
403
|
-
No-op for JSON requests — safe to always add. Options: `maxFileSize`, `maxFiles`, `allowedMimeTypes`, `filesKey`.
|
|
404
|
-
|
|
405
|
-
## Migrations
|
|
406
|
-
|
|
407
|
-
```typescript
|
|
408
|
-
import { defineMigration, MigrationRunner } from '@classytic/arc/migrations';
|
|
409
|
-
|
|
410
|
-
const v2 = defineMigration({
|
|
411
|
-
version: 2,
|
|
412
|
-
resource: 'product',
|
|
413
|
-
up: async (db) => {
|
|
414
|
-
await db.collection('products').updateMany({}, { $rename: { oldField: 'newField' } });
|
|
415
|
-
},
|
|
416
|
-
down: async (db) => {
|
|
417
|
-
await db.collection('products').updateMany({}, { $rename: { newField: 'oldField' } });
|
|
418
|
-
},
|
|
419
|
-
});
|
|
420
|
-
|
|
421
|
-
const runner = new MigrationRunner(mongoose.connection.db);
|
|
422
|
-
await runner.up([v2]);
|
|
423
|
-
```
|
|
424
|
-
|
|
425
|
-
## OpenAPI & External Paths
|
|
426
|
-
|
|
427
|
-
Arc auto-generates OpenAPI 3.0 specs from resource definitions. External integrations (auth adapters, custom routes) inject their paths via `ExternalOpenApiPaths`.
|
|
428
|
-
|
|
429
|
-
```typescript
|
|
430
|
-
import type { ExternalOpenApiPaths } from '@classytic/arc/docs';
|
|
431
|
-
|
|
432
|
-
const externalPaths: ExternalOpenApiPaths = {
|
|
433
|
-
paths: { '/api/auth/sign-in': { post: { summary: 'Sign in', ... } } },
|
|
434
|
-
schemas: { User: { type: 'object', properties: { ... } } },
|
|
435
|
-
securitySchemes: {
|
|
436
|
-
cookieAuth: { type: 'apiKey', in: 'cookie', name: 'session_token' },
|
|
437
|
-
},
|
|
438
|
-
tags: [{ name: 'Authentication' }],
|
|
439
|
-
// Declare additional security alternatives for Arc resource paths
|
|
440
|
-
resourceSecurity: [{ apiKeyAuth: [], orgHeader: [] }],
|
|
441
|
-
};
|
|
442
|
-
```
|
|
443
|
-
|
|
444
|
-
**`resourceSecurity`** — declarative registration of auth alternatives for resource paths:
|
|
445
|
-
- Each array item is **OR**'d with `bearerAuth` (the default)
|
|
446
|
-
- Keys within the same object are **AND**'d (all required together)
|
|
447
|
-
- Example: `[{ apiKeyAuth: [], orgHeader: [] }]` → "bearer OR (api-key AND org-header)"
|
|
448
|
-
|
|
449
|
-
Arc's Better Auth adapter (`extractBetterAuthOpenApi`) auto-populates `resourceSecurity` when the `apiKey()` plugin is detected — no manual configuration needed.
|
|
450
|
-
|
|
451
|
-
**Security scheme definitions:**
|
|
452
|
-
|
|
453
|
-
| Scheme | Type | Source | Always present? |
|
|
454
|
-
|--------|------|--------|-----------------|
|
|
455
|
-
| `bearerAuth` | HTTP Bearer | Arc core | Yes |
|
|
456
|
-
| `orgHeader` | API Key (`x-organization-id`) | Arc core | Yes (multi-tenant) |
|
|
457
|
-
| `cookieAuth` | API Key (cookie) | Better Auth adapter | When Better Auth active |
|
|
458
|
-
| `apiKeyAuth` | API Key (`x-api-key`) | Better Auth adapter | When `apiKey()` plugin active |
|
|
459
|
-
|
|
460
|
-
## Deployment
|
|
461
|
-
|
|
462
|
-
Arc requires Node.js APIs (`node:crypto`, `AsyncLocalStorage`). Use `toFetchHandler()` for serverless/edge.
|
|
463
|
-
|
|
464
|
-
| Environment | Preset | Handler | Notes |
|
|
465
|
-
|-------------|--------|---------|-------|
|
|
466
|
-
| Docker/K8s | `production` | `app.listen()` | Full production |
|
|
467
|
-
| Google Cloud Run | `production` | `app.listen()` | Set min-instances > 0 for WebSocket |
|
|
468
|
-
| Railway/Render/Fly.io | `production` | `app.listen()` | Works with zero config |
|
|
469
|
-
| AWS Lambda | `edge` | `toFetchHandler()` | Node.js runtime |
|
|
470
|
-
| Vercel Serverless | `edge` | `toFetchHandler()` | Node.js runtime |
|
|
471
|
-
| Cloudflare Workers | `edge` | `toFetchHandler()` | Enable `nodejs_compat` in wrangler.toml |
|
|
472
|
-
|
|
473
|
-
**Edge handler:**
|
|
474
|
-
```typescript
|
|
475
|
-
import { createApp, toFetchHandler } from '@classytic/arc/factory';
|
|
476
|
-
const app = await createApp({ preset: 'edge', auth: { type: 'jwt', jwt: { secret } } });
|
|
477
|
-
export default { fetch: toFetchHandler(app) }; // Cloudflare Workers / any fetch-based runtime
|
|
478
|
-
```
|
|
479
|
-
|
|
480
|
-
**Production checklist:**
|
|
481
|
-
|
|
482
|
-
```typescript
|
|
483
|
-
// Validate env vars at startup
|
|
484
|
-
if (!process.env.JWT_SECRET || process.env.JWT_SECRET.length < 32) throw new Error('...');
|
|
485
|
-
|
|
486
|
-
const app = await createApp({
|
|
487
|
-
preset: 'production',
|
|
488
|
-
auth: { type: 'jwt', jwt: { secret: process.env.JWT_SECRET } },
|
|
489
|
-
cors: { origin: process.env.ALLOWED_ORIGINS?.split(',') ?? [], credentials: true },
|
|
490
|
-
rateLimit: { max: 100, timeWindow: '1 minute' },
|
|
491
|
-
arcPlugins: {
|
|
492
|
-
queryCache: true,
|
|
493
|
-
// Behind a load balancer: fail readiness first, keep serving while it
|
|
494
|
-
// deregisters, then close. No manual process.on('SIGTERM') — the plugin
|
|
495
|
-
// owns the signals, and a second handler skips the drain.
|
|
496
|
-
gracefulShutdown: { drainDelayMs: 10_000 },
|
|
497
|
-
},
|
|
498
|
-
});
|
|
499
|
-
```
|
|
500
|
-
|
|
501
|
-
## Distributed Runtime
|
|
502
|
-
|
|
503
|
-
`runtime: 'distributed'` is the "more than one replica" switch. It refuses to boot when something in the app holds state that only exists in **this** process. Two checks, one policy:
|
|
504
|
-
|
|
505
|
-
**1. Constructor-time guard** — what `createApp` can see in its own options, checked before any boot cost:
|
|
506
|
-
|
|
507
|
-
- `stores.events` — always required
|
|
508
|
-
- `stores.cache` — only when `arcPlugins.caching` enabled
|
|
509
|
-
- `stores.queryCache` — only when `arcPlugins.queryCache` enabled
|
|
510
|
-
- `stores.idempotency` — warn only (per-resource opt-in)
|
|
511
|
-
- `rateLimit` — needs a shared store: `{ redis: client }` or `{ store: CustomStore }`. Both forms count; `rateLimit: false` opts out.
|
|
512
|
-
- `arcPlugins.schedules` — needs `lock` (a `LockAdapter`, for a fleet where any replica may arm schedules) **or** `singleReplica: true` (exactly one replica arms them — the `role: 'scheduler'` deployment pinned at 1). Without one, boot fails: otherwise every replica fires every tick, and duplicate side effects are two invoices, not a stale cache. `singleReplica` is a claim about your deployment — scale that deployment past one replica and it becomes false.
|
|
513
|
-
|
|
514
|
-
**2. Capability audit** (end of boot) — everything wired inside `plugins()`, `bootstrap[]`, or a module phase, which the guard above cannot inspect. Subsystems declare via `declareRuntimeCapability`; an undeclared-shared memory default **fails the boot in one error naming every violator**, so you fix them in one pass rather than one restart each.
|
|
515
|
-
|
|
516
|
-
What declares itself, and what fixes it:
|
|
517
|
-
|
|
518
|
-
| Subsystem | Default | Shared option |
|
|
519
|
-
|---|---|---|
|
|
520
|
-
| `auth.sessions` | `MemorySessionStore` | `RedisSessionStore` (`@classytic/arc/auth/redis`) |
|
|
521
|
-
| `usage.store` | `MemoryUsageStore` | `RedisUsageStore` (`@classytic/arc/usage`) or `@classytic/mongokit/usage` |
|
|
522
|
-
| `audit.store` | `MemoryAuditStore` | `repository: yourRepo` (any kit) |
|
|
523
|
-
| `cache.query` | `MemoryCacheStore` | `RedisCacheStore` (`@classytic/arc/cache`) |
|
|
524
|
-
| `permissions.dynamic-cache` | internal memory | `cacheStore:` — **and pass `fastify:`**, the matrix has no handle of its own so it is invisible to the audit without it |
|
|
525
|
-
| `websocket.adapter` | `LocalWebSocketAdapter` | Redis adapter (`@classytic/arc/integrations/websocket-redis`) |
|
|
526
|
-
| `websocket.pushref-store` | memory | Redis pushRef store |
|
|
527
|
-
| `webhooks.store` | memory | shared store, or durable mode |
|
|
528
|
-
| `http.response-cache` | memory | **nothing — declared `accepted`.** Per-replica by design; correctness comes from short TTLs. Logged, never a failure. |
|
|
529
|
-
|
|
530
|
-
### Circuit breakers count per replica unless you say otherwise
|
|
531
|
-
|
|
532
|
-
`CircuitBreaker` state is in-process. With 50 pods and `failureThreshold: 5`, a dead downstream absorbs **250 real requests** before anything opens — each pod rediscovers the same outage independently. Share the failure window:
|
|
533
|
-
|
|
534
|
-
```typescript
|
|
535
|
-
import { CircuitBreaker, RedisCircuitBreakerState } from '@classytic/arc/utils';
|
|
536
|
-
|
|
537
|
-
const shared = new RedisCircuitBreakerState({ redis }); // fixed window, default 60s
|
|
538
|
-
|
|
539
|
-
const payments = new CircuitBreaker(charge, {
|
|
540
|
-
name: 'stripe.charges', // REQUIRED with sharedState — the key every replica counts under
|
|
541
|
-
failureThreshold: 5,
|
|
542
|
-
sharedState: shared,
|
|
543
|
-
});
|
|
544
|
-
```
|
|
545
|
-
|
|
546
|
-
First replica trips at the threshold; every other trips on its **next** failure. It shares the failure *signal*, not the state machine — each replica still owns its own OPEN/HALF_OPEN probing, which avoids needing consensus over who probes. Nothing touches the network on the success path, the failure path never *waits* on the store, and a store that throws degrades to local counting rather than disabling the breaker.
|
|
547
|
-
|
|
548
|
-
Hosts declare their own too — a replica-local cache you built in `plugins()` belongs in the audit:
|
|
549
|
-
|
|
550
|
-
```typescript
|
|
551
|
-
import { declareRuntimeCapability } from '@classytic/arc/utils';
|
|
552
|
-
|
|
553
|
-
declareRuntimeCapability(fastify, {
|
|
554
|
-
subsystem: 'billing.sequence-cache',
|
|
555
|
-
durability: 'memory', // 'memory' | 'shared'
|
|
556
|
-
detail: 'invoice numbering cached per process',
|
|
557
|
-
// accepted: true, // only when per-process is INTENDED
|
|
558
|
-
});
|
|
559
|
-
```
|
|
560
|
-
|
|
561
|
-
Declare from anywhere a registration reaches — `plugins()`, a module phase, or inside your own encapsulated `fastify.register()`; all land in the one audit. `accepted: true` is for state that is per-process **by design**; it must be stated by the declarant, never inferred.
|
|
562
|
-
|
|
563
|
-
**Migration note:** a distributed app that booted fine before 2.41 can now fail on a default it was silently running replica-local (usage counters and audit trails were the common ones). The boot error names each. That is the bug surfacing, not a new one.
|
|
564
|
-
|
|
565
|
-
## Under-Pressure
|
|
566
|
-
|
|
567
|
-
Production preset: `maxEventLoopDelay: 3000` (avoids false 503s on Render/Railway/Fly.io). Override: `underPressure: { maxEventLoopDelay: 500 }`. Disable: `underPressure: false`.
|
|
568
|
-
|
|
569
|
-
## CORS
|
|
570
|
-
|
|
571
|
-
Production warns (not throws) when origin missing. `origin: '*'` from env is allowed. Smart CORS auto-converts `credentials: true` + `origin: '*'` to `origin: true`, and (2.22) auto-merges arc's protocol headers (`x-organization-id`, `x-arc-scope`, `x-request-id`) into any host-declared `allowedHeaders` allow-list — hosts never enumerate framework internals.
|
|
572
|
-
|
|
573
|
-
### Mobile apps (Capacitor / Ionic / React Native webviews)
|
|
574
|
-
|
|
575
|
-
Arc needs no special mode — mobile is a CORS + auth-transport recipe:
|
|
576
|
-
|
|
577
|
-
```typescript
|
|
578
|
-
cors: {
|
|
579
|
-
// Webview origins alongside your web domains. Also add these to
|
|
580
|
-
// Better Auth's trustedOrigins when using BA.
|
|
581
|
-
origin: [...webOrigins, 'https://localhost', 'capacitor://localhost'],
|
|
582
|
-
credentials: true,
|
|
583
|
-
// Optional allow-list — arc's own headers auto-merge (2.22); you only
|
|
584
|
-
// list YOUR custom ones. Omit entirely to use reflection mode.
|
|
585
|
-
allowedHeaders: ['Content-Type', 'Authorization'],
|
|
586
|
-
// BA bearer plugin returns the fresh session token in this RESPONSE
|
|
587
|
-
// header — without exposing it, cross-origin JS cannot READ it and
|
|
588
|
-
// app login dies silently. The one mobile knob arc can't infer.
|
|
589
|
-
exposedHeaders: ['set-auth-token'],
|
|
590
|
-
},
|
|
591
|
-
trustProxy: true, // webviews arrive through your LB/tunnel
|
|
592
|
-
```
|
|
593
|
-
|
|
594
|
-
Native (non-webview) HTTP clients send no `Origin` header — CORS doesn't apply to them at all; bearer auth just works.
|
|
595
|
-
|
|
596
|
-
## Metrics Plugin
|
|
597
|
-
|
|
598
|
-
Prometheus-compatible metrics endpoint — zero external dependencies:
|
|
599
|
-
|
|
600
|
-
```typescript
|
|
601
|
-
import { metricsPlugin } from '@classytic/arc/plugins';
|
|
602
|
-
|
|
603
|
-
await fastify.register(metricsPlugin, {
|
|
604
|
-
path: '/_metrics', // default
|
|
605
|
-
prefix: 'arc', // metric name prefix (default: 'arc')
|
|
606
|
-
onCollect: (metrics) => pushToOTLP(metrics), // optional OTLP push
|
|
607
|
-
});
|
|
608
|
-
|
|
609
|
-
// GET /_metrics → Prometheus text format
|
|
610
|
-
```
|
|
611
|
-
|
|
612
|
-
**Built-in counters**: `arc_http_requests_total`, `arc_http_request_duration_seconds`, `arc_crud_operations_total`, `arc_cache_hits_total`, `arc_cache_misses_total`, `arc_events_published_total`, `arc_events_consumed_total`, `arc_circuit_breaker_state`.
|
|
613
|
-
|
|
614
|
-
**Programmatic access**: `fastify.metrics.recordOperation(resource, op, status, durationMs)`, `.recordCacheHit(resource)`, `.recordEventPublish(type)`, `.reset()`.
|
|
615
|
-
|
|
616
|
-
## API Versioning Plugin
|
|
617
|
-
|
|
618
|
-
Header-based or URL prefix-based versioning with deprecation warnings:
|
|
619
|
-
|
|
620
|
-
```typescript
|
|
621
|
-
import { versioningPlugin } from '@classytic/arc/plugins';
|
|
622
|
-
|
|
623
|
-
// Header-based: clients send Accept-Version: 2
|
|
624
|
-
await fastify.register(versioningPlugin, {
|
|
625
|
-
type: 'header',
|
|
626
|
-
deprecated: ['1'],
|
|
627
|
-
sunset: '2025-12-01',
|
|
628
|
-
});
|
|
629
|
-
|
|
630
|
-
// Prefix-based: /v2/products
|
|
631
|
-
await fastify.register(versioningPlugin, { type: 'prefix' });
|
|
632
|
-
```
|
|
633
|
-
|
|
634
|
-
**Headers set**: `x-api-version` on every response. `Deprecation: true` + `Sunset` for deprecated versions. Access via `request.apiVersion`.
|
|
635
|
-
|
|
636
|
-
## Per-Tenant Rate Limiting
|
|
637
|
-
|
|
638
|
-
Scope-aware rate limit key generator — isolates rate limits by org, user, or IP:
|
|
639
|
-
|
|
640
|
-
```typescript
|
|
641
|
-
import { createTenantKeyGenerator } from '@classytic/arc/scope';
|
|
642
|
-
|
|
643
|
-
const app = await createApp({
|
|
644
|
-
rateLimit: {
|
|
645
|
-
max: 100,
|
|
646
|
-
timeWindow: '1 minute',
|
|
647
|
-
keyGenerator: createTenantKeyGenerator(),
|
|
648
|
-
},
|
|
649
|
-
});
|
|
650
|
-
```
|
|
651
|
-
|
|
652
|
-
**Key resolution**: `member` → `organizationId`, `authenticated` → `userId`, `elevated` → `organizationId ?? userId`, `public` → IP. Custom strategy: `createTenantKeyGenerator({ strategy: (ctx) => ctx.ip })`.
|
|
653
|
-
|
|
654
|
-
## Event Outbox
|
|
655
|
-
|
|
656
|
-
Transactional outbox pattern — at-least-once delivery even if transport is down:
|
|
657
|
-
|
|
658
|
-
```typescript
|
|
659
|
-
import { EventOutbox, MemoryOutboxStore } from '@classytic/arc/events';
|
|
660
|
-
import { Repository } from '@classytic/mongokit';
|
|
661
|
-
|
|
662
|
-
// Dev
|
|
663
|
-
const outbox = new EventOutbox({ store: new MemoryOutboxStore(), transport: redisTransport });
|
|
664
|
-
|
|
665
|
-
// Production — any RepositoryLike
|
|
666
|
-
const outbox = new EventOutbox({
|
|
667
|
-
repository: new Repository(OutboxModel),
|
|
668
|
-
transport: redisTransport,
|
|
669
|
-
});
|
|
670
|
-
|
|
671
|
-
// In business logic (same DB transaction via `{ session }`)
|
|
672
|
-
await outbox.store(event, { session });
|
|
673
|
-
|
|
674
|
-
// Relay cron (runs every few seconds)
|
|
675
|
-
const relayed = await outbox.relay(); // publishes pending → transport
|
|
676
|
-
```
|
|
677
|
-
|
|
678
|
-
**Prefer the module form** — it owns the relay schedule, shutdown, and a readiness check, so none of that is hand-wired:
|
|
679
|
-
|
|
680
|
-
```typescript
|
|
681
|
-
import { createOutboxModule, exponentialBackoff, repositoryAsOutboxStore } from '@classytic/arc/events';
|
|
682
|
-
|
|
683
|
-
const outbox = createOutboxModule({
|
|
684
|
-
store: repositoryAsOutboxStore(new Repository(OutboxModel)),
|
|
685
|
-
// Bounds retries AND log volume. `attempts` is the DURABLE count (it survives relay
|
|
686
|
-
// restarts and is shared across relays), so a poison event really does stop at 5.
|
|
687
|
-
failurePolicy: ({ attempts }) =>
|
|
688
|
-
attempts >= 5 ? { deadLetter: true } : { retryAt: exponentialBackoff({ attempt: attempts }) },
|
|
689
|
-
health: { relayLagUnhealthyMs: 5 * 60_000, probeCacheMs: 5_000 },
|
|
690
|
-
});
|
|
691
|
-
// createApp({ modules: [outbox] }); consumers declare dependsOn: ['outbox'].
|
|
692
|
-
```
|
|
693
|
-
|
|
694
|
-
- `requestDrain()` — nudge a pass after commit (milliseconds, not `relayEveryMs`); runs outside the caller's request scope.
|
|
695
|
-
- `drain()` — await delivery, cascades included. For tests and a shutdown that should empty the queue.
|
|
696
|
-
- `health()` + readiness check `<name>.relay` — **non-critical** (a stalled relay is a cluster problem; pulling one pod would not drain it). Unhealthy on any dead letter or pending lag past the threshold. The probe reuses a reading for `probeCacheMs` so N replicas × probe rate do not become N count queries a second on the outbox table.
|
|
697
|
-
|
|
698
|
-
**OutboxStore contract** (`@classytic/primitives/outbox`): required `save`, `getPending`, `acknowledge`; optional `claimPending` / `claimPendingFenced` (lease + fencing token, and the durable `attempts`), `fail`, `getDeadLettered`, `requeue`, `purge`, `countByStatus`, `oldestPendingAgeMs`. Prove a custom store with `runOutboxStoreContract` from `@classytic/arc/testing/outbox`. When you pass `repository`, arc adapts it internally.
|
|
699
|
-
|
|
700
|
-
## Bulk Operations Preset
|
|
701
|
-
|
|
702
|
-
Adds bulk CRUD routes — repository must provide `createMany`, `updateMany`, `deleteMany`:
|
|
703
|
-
|
|
704
|
-
```typescript
|
|
705
|
-
import { createMongooseAdapter } from '@classytic/mongokit/adapter';
|
|
706
|
-
import { buildCrudSchemasFromModel } from '@classytic/mongokit';
|
|
707
|
-
|
|
708
|
-
defineResource({
|
|
709
|
-
name: 'product',
|
|
710
|
-
adapter: createMongooseAdapter({ model, repository, schemaGenerator: buildCrudSchemasFromModel }),
|
|
711
|
-
presets: ['bulk'], // adds POST/PATCH/DELETE /{resource}/bulk
|
|
712
|
-
});
|
|
713
|
-
|
|
714
|
-
// Or with options
|
|
715
|
-
presets: [bulkPreset({ operations: ['createMany', 'updateMany'], maxCreateItems: 500 })]
|
|
716
|
-
```
|
|
717
|
-
|
|
718
|
-
**Routes**: `POST /bulk` (body: `{ items }`) → `createMany`, `PATCH /bulk` (body: `{ filter, data }`) → `updateMany`, `DELETE /bulk` (body: `{ filter }`) → `deleteMany`. Permissions inherit from `create`/`update`/`delete`.
|
|
719
|
-
|
|
720
|
-
## Compensating Transaction
|
|
721
|
-
|
|
722
|
-
In-process rollback primitive — runs steps in order, compensates in reverse on failure.
|
|
723
|
-
For distributed sagas across services, use `@classytic/streamline` or a dedicated workflow orchestrator.
|
|
724
|
-
|
|
725
|
-
```typescript
|
|
726
|
-
import { withCompensation } from '@classytic/arc/utils';
|
|
727
|
-
|
|
728
|
-
const result = await withCompensation('place-order', [
|
|
729
|
-
{
|
|
730
|
-
name: 'reserve-inventory',
|
|
731
|
-
execute: async (ctx) => {
|
|
732
|
-
const res = await inventoryService.reserve(ctx.items);
|
|
733
|
-
ctx.reservationId = res.id;
|
|
734
|
-
return res;
|
|
735
|
-
},
|
|
736
|
-
compensate: async (_ctx, result) => {
|
|
737
|
-
await inventoryService.release(result.id);
|
|
738
|
-
},
|
|
739
|
-
},
|
|
740
|
-
{
|
|
741
|
-
name: 'charge-payment',
|
|
742
|
-
execute: async (ctx) => await paymentService.charge(ctx.total),
|
|
743
|
-
compensate: async (_ctx, result) => await paymentService.refund(result.chargeId),
|
|
744
|
-
},
|
|
745
|
-
{
|
|
746
|
-
name: 'send-confirmation',
|
|
747
|
-
execute: async (ctx) => await emailService.send(ctx.email),
|
|
748
|
-
// No compensate — emails can't be unsent
|
|
749
|
-
},
|
|
750
|
-
], { items: cart.items, total: cart.total, email: user.email });
|
|
751
|
-
|
|
752
|
-
if (!result.success) {
|
|
753
|
-
console.error(`Saga failed at ${result.failedStep}: ${result.error}`);
|
|
754
|
-
// Compensation already ran for completed steps
|
|
755
|
-
}
|
|
756
|
-
```
|
|
757
|
-
|
|
758
|
-
**`defineCompensation()`** — reusable definition:
|
|
759
|
-
|
|
760
|
-
```typescript
|
|
761
|
-
const placeOrder = defineCompensation('place-order', steps);
|
|
762
|
-
await placeOrder.execute({ items, total, email });
|
|
763
|
-
```
|
|
764
|
-
|
|
765
|
-
**Fire-and-forget steps** — don't block, don't compensate, errors swallowed:
|
|
766
|
-
|
|
767
|
-
```typescript
|
|
768
|
-
await withCompensation('checkout', [
|
|
769
|
-
{ name: 'save-order', execute: saveOrder, compensate: cancelOrder },
|
|
770
|
-
{ name: 'send-email', execute: sendEmail, fireAndForget: true }, // non-blocking
|
|
771
|
-
{ name: 'charge', execute: chargeCard, compensate: refundCard },
|
|
772
|
-
]);
|
|
773
|
-
// 'charge' runs immediately after 'save-order' — doesn't wait for email
|
|
774
|
-
```
|
|
775
|
-
|
|
776
|
-
**Lifecycle hooks** — wire to Arc events, logging, or metrics:
|
|
777
|
-
|
|
778
|
-
```typescript
|
|
779
|
-
await withCompensation('checkout', steps, { orderId }, {
|
|
780
|
-
onStepComplete: (stepName, result) => {
|
|
781
|
-
fastify.events.publish(`checkout.${stepName}.completed`, result);
|
|
782
|
-
},
|
|
783
|
-
onStepFailed: (stepName, error) => {
|
|
784
|
-
fastify.events.publish(`checkout.${stepName}.failed`, { error: error.message });
|
|
785
|
-
},
|
|
786
|
-
onCompensate: (stepName) => {
|
|
787
|
-
fastify.log.warn(`Compensated: ${stepName}`);
|
|
788
|
-
},
|
|
789
|
-
});
|
|
790
|
-
```
|
|
791
|
-
|
|
792
|
-
**In a custom route with Arc auth:**
|
|
793
|
-
|
|
794
|
-
```typescript
|
|
795
|
-
defineResource({
|
|
796
|
-
name: 'order',
|
|
797
|
-
routes: [{
|
|
798
|
-
method: 'POST',
|
|
799
|
-
path: '/:id/checkout',
|
|
800
|
-
permissions: requireAuth(),
|
|
801
|
-
rawHandler: async (request, reply) => {
|
|
802
|
-
const result = await withCompensation('checkout', steps, { orderId: request.params.id });
|
|
803
|
-
if (!result.success) return reply.code(422).send({ error: result.error });
|
|
804
|
-
return reply.send({ data: result.results });
|
|
805
|
-
},
|
|
806
|
-
}],
|
|
807
|
-
});
|
|
808
|
-
```
|
|
809
|
-
|
|
810
|
-
**Compensation errors**: collected in `result.compensationErrors[]` without stopping rollback. **Context**: mutable `Record<string, unknown>` shared across all steps.
|
|
811
|
-
|
|
812
|
-
**Scope**: In-process primitive. Process crash = no compensation. For durable distributed workflows, use Temporal, Inngest, or `@classytic/streamline`.
|
|
813
|
-
|
|
814
|
-
## Multi-Domain Deployment
|
|
815
|
-
|
|
816
|
-
Arc supports multi-domain applications through COMPOSITION — it deliberately owns no domain routing, domain databases, certificate provisioning, or wildcard-domain management. The deployment shape:
|
|
817
|
-
|
|
818
|
-
```
|
|
819
|
-
api.example.com → arc API
|
|
820
|
-
auth.example.com → Better Auth (or auth module)
|
|
821
|
-
events.example.com → SSE/WebSocket edge tier
|
|
822
|
-
admin.example.com → frontend
|
|
823
|
-
customer-domain.com → gateway/domain resolver → tenant context
|
|
824
|
-
```
|
|
825
|
-
|
|
826
|
-
The primitives are already there: CORS allowlists, Better Auth trusted origins, tenant scope, request context, `trustProxy` configuration, resource/module prefixes.
|
|
827
|
-
|
|
828
|
-
**Custom tenant domains**: resolve the domain at a gateway or an early host plugin, then convert it into a trusted `RequestScope` — a small host-provided resolver is enough:
|
|
829
|
-
|
|
830
|
-
```typescript
|
|
831
|
-
// onRequest, before auth: map host → tenant hint
|
|
832
|
-
const tenant = await resolveTenantDomain(request.hostname); // → { organizationId } | null
|
|
833
|
-
```
|
|
834
|
-
|
|
835
|
-
Then validate membership or service scope through the NORMAL permission path. **Never treat raw `Host` / `X-Forwarded-Host` as tenant authorization by itself** — behind a misconfigured proxy those are attacker-controlled (see the `trustProxy` boot warning). The header selects the tenant *candidate*; membership resolution authorizes it — same rule `resolveOrgFromHeader` follows for `x-organization-id`.
|