@classytic/arc 2.45.2 → 2.46.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-CiicKz2Z.d.mts → EventTransport-CYEoCJGe.d.mts} +0 -2
- package/dist/{EventTransport-DHb1tpu-.mjs → EventTransport-DNgD9NP4.mjs} +3 -4
- package/dist/{HookSystem-C1u0EUnt.mjs → HookSystem-DRbPzEcP.mjs} +3 -4
- package/dist/{QueryCache--5uAuYPW.d.mts → QueryCache-DdvrGG8Q.d.mts} +1 -3
- package/dist/{ResourceRegistry-D2jXWVN_.mjs → ResourceRegistry-Douk51fa.mjs} +15 -4
- package/dist/{acquire-DTkA8Lme.mjs → acquire-RbtvDg9s.mjs} +2 -3
- package/dist/{actionPermissions-DRVk6m7x.mjs → actionPermissions-De0AJ7hm.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-DeZMrHcm.mjs} +5 -6
- package/dist/{base-CZyixEQR.d.mts → base-HXNgPQww.d.mts} +1 -7
- package/dist/{boundedMap-DkKiPifd.mjs → boundedMap-2WBh3gM9.mjs} +2 -3
- package/dist/{buildHandler-BiZ4VATS.mjs → buildHandler-DxVOOBpw.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-BYRwYrUo.mjs} +3 -4
- package/dist/{claimed-ChI13rUR.mjs → claimed-DYlELdnm.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-CHZMUwBW.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-D9rS2BxO.mjs} +9 -12
- package/dist/{createActionRouter-CvH84dyx.mjs → createActionRouter-0qkCRzTL.mjs} +7 -8
- package/dist/{createAggregationRouter-DGyK2Hp6.mjs → createAggregationRouter-CUf5Esd9.mjs} +9 -10
- package/dist/{createApp-CKjZpmq9.mjs → createApp-DZIXfDKD.mjs} +49 -62
- package/dist/{createMcpServer-DSztofa9.d.mts → createMcpServer-DeVpqQF-.d.mts} +1 -3
- package/dist/{defineAggregation-BLza7Ca4.mjs → defineAggregation-bmKQ4NmC.mjs} +2 -3
- package/dist/{defineResource-CEo0gDCb.mjs → defineResource-CGmdmGwh.mjs} +78 -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-BJTsSnke.mjs → elevation-CzhqAyVN.mjs} +9 -10
- package/dist/{elevation-BW2J3tNj.d.mts → elevation-DPD0hcU-.d.mts} +0 -2
- 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-dFyGOEoB.mjs} +16 -6
- package/dist/{errors-grZkIA8N.mjs → errors-BY8vzlP4.mjs} +2 -3
- package/dist/{errors-JYc9vwqE.d.mts → errors-DTo0me1o.d.mts} +0 -2
- package/dist/{eventPlugin-BtmA4-3P.d.mts → eventPlugin-BY38F6yK.d.mts} +1 -7
- package/dist/{eventPlugin-ItcYBGUs.mjs → eventPlugin-eMhAPtQA.mjs} +10 -12
- package/dist/{eventTypes-Ck6fD3ne.mjs → eventTypes-Do2KYeJx.mjs} +5 -8
- package/dist/events/index.d.mts +4 -16
- package/dist/events/index.mjs +8 -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-Dtn0IIRn.d.mts} +4 -10
- package/dist/{fields-BBSpf8pS.d.mts → fields-JTkrtO-r.d.mts} +0 -2
- package/dist/{fields-BRX0Krcj.mjs → fields-LnbCcvsw.mjs} +2 -3
- package/dist/{filter-merge-CDc7YMwX.mjs → filter-merge-BAWi019Q.mjs} +2 -3
- package/dist/{generate-DCGuEbqI.d.mts → generate-C-g_KOkV.d.mts} +0 -4
- package/dist/{generate-hvg7V2g1.mjs → generate-oXoDnpJf.mjs} +7 -12
- package/dist/{headers-Cqkg4LzI.mjs → headers-DBd3Qheo.mjs} +3 -4
- package/dist/{health-PVt0VjOx.mjs → health-BlJu9GXS.mjs} +2 -3
- package/dist/{health-DyeP3mTW.mjs → health-Dp-3EC9o.mjs} +4 -7
- package/dist/hooks/index.d.mts +1 -1
- package/dist/hooks/index.mjs +2 -2
- package/dist/idempotency/index.d.mts +3 -9
- package/dist/idempotency/index.mjs +10 -13
- 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-BTxzJ_MN.d.mts} +67 -25
- package/dist/{index-CUJvoyw3.d.mts → index-Bqfo8hLz.d.mts} +2 -24
- package/dist/{index-uhkUA5-U.d.mts → index-CUdaoCYt.d.mts} +13 -23
- package/dist/{index-WH7xgvxS.d.mts → index-DyJFTJLA.d.mts} +31 -92
- package/dist/index.d.mts +7 -9
- package/dist/index.mjs +12 -13
- package/dist/{init-jC3rMPzb.mjs → init-BOaNkLYb.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 +4 -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-DpRpKR_K.mjs} +3 -4
- package/dist/{keys-C1vFuSbv.mjs → keys-FBz6Ull-.mjs} +2 -3
- package/dist/{loadResources-CHPDyIPn.mjs → loadResources-Bx1sKPnF.mjs} +4 -5
- package/dist/{loadResourcesFromEntry-BkHHTu_B.mjs → loadResourcesFromEntry-b_jcqbxh.mjs} +3 -4
- package/dist/logger/index.d.mts +1 -3
- package/dist/logger/index.mjs +2 -2
- package/dist/{logger-C5bvCiAK.mjs → logger-CbFcIEBZ.mjs} +3 -5
- package/dist/{mcpPlugin-C9qohJCF.mjs → mcpPlugin-yix548XX.mjs} +41 -60
- package/dist/{memory-CxiTwT0j.mjs → memory-Bgw5dn8N.mjs} +4 -5
- package/dist/{metrics-Ckp2zRy-.mjs → metrics-CZDQWVjS.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-Dsc_nKL5.mjs} +2 -3
- package/dist/{multiTenant-CAtYlW6H.d.mts → multiTenant-XCxAUlru.d.mts} +1 -5
- package/dist/{multipartBody-BFasGtP9.mjs → multipartBody-B85ek8Kj.mjs} +2 -3
- package/dist/observeSend-BK-JN1jK.mjs +20 -0
- package/dist/{openapi-DAPxjYHX.mjs → openapi-Co7hl073.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-XvUThpqn.d.mts} +2 -8
- package/dist/{outbox-module-B4FAkx3A.mjs → outbox-module-mg9kDYkd.mjs} +13 -17
- package/dist/permissions/index.d.mts +4 -4
- package/dist/permissions/index.mjs +7 -7
- package/dist/{permissions-B14c3OMp.mjs → permissions-A1oKtpiC.mjs} +19 -29
- package/dist/{pipe-CQv7PsAK.mjs → pipe-Czpw9U2n.mjs} +3 -4
- package/dist/pipeline/index.d.mts +1 -9
- package/dist/pipeline/index.mjs +5 -8
- package/dist/{plan-CpnTykjb.mjs → plan-KVseuBCL.mjs} +5 -9
- package/dist/{plugin-DXTjVg_Q.mjs → plugin-DTWt_8C3.mjs} +130 -62
- 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-msB9X3yw.mjs} +2 -3
- 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-qKCehiJM.mjs} +11 -18
- package/dist/{projection-CgfSLOSM.mjs → projection-ClBqtsIw.mjs} +3 -4
- package/dist/{pushref-registry-UxCkoA4C.d.mts → pushref-registry-d86QUaSq.d.mts} +0 -6
- package/dist/{queryCachePlugin-D0HUISHJ.mjs → queryCachePlugin-3gJj5Rbz.mjs} +8 -10
- package/dist/{queryCachePlugin-C2lZjTxk.d.mts → queryCachePlugin-DYQUyeJ9.d.mts} +2 -4
- package/dist/{rateLimitKey-AvkBOMkl.mjs → rateLimitKey-Kro---xl.mjs} +2 -3
- package/dist/{realtime-CbWtVbqK.mjs → realtime-Ber8uJN2.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-BA-_vFYk.mjs} +7 -12
- package/dist/{renewingLease-CykpeNcQ.mjs → renewingLease-CMY8YOcc.mjs} +2 -3
- package/dist/{replyHelpers-DA51IZio.mjs → replyHelpers-DK9P_XSz.mjs} +3 -4
- package/dist/{requestContext-DIWHKDtQ.mjs → requestContext-GYO_0gEw.mjs} +2 -3
- package/dist/{requirement-CbiLdQ1n.d.mts → requirement-CTRQjjQx.d.mts} +0 -2
- package/dist/{requirement-Cp_fsMDL.mjs → requirement-DeNjZIH3.mjs} +2 -3
- package/dist/{resourceRateLimit-Wf6d6FL9.d.mts → resourceRateLimit-DCWglD7V.d.mts} +1 -3
- package/dist/{resourceRateLimit-BFuluodF.mjs → resourceRateLimit-tHLbrtWc.mjs} +3 -4
- package/dist/{rolldown-runtime-D_lMdYOd.mjs → rolldown-runtime-Kv1fZdLg.mjs} +2 -3
- package/dist/{routeValidator-DuLonYwr.mjs → routeValidator-C_H5NanI.mjs} +2 -3
- package/dist/{runtimeCapabilities-CydRfm0i.mjs → runtimeCapabilities-DWqbxkyw.mjs} +2 -3
- package/dist/{schedules-B693KXxa.mjs → schedules-eO_RzhCU.mjs} +132 -9
- package/dist/{schemaConverter-DNvZWTV6.mjs → schemaConverter-DBJrPZN4.mjs} +3 -4
- package/dist/{schemaIR-REV2y7Wd.mjs → schemaIR-CEScKT2v.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-B-Sm9m_E.mjs} +5 -6
- package/dist/{sessionManager-qimlKV0P.d.mts → sessionManager-CdvDF04x.d.mts} +2 -4
- package/dist/{shutdown-CfrqPR7A.mjs → shutdown-DzLFbe27.mjs} +2 -3
- package/dist/{simpleEqualityMatcher-BJwfuRKP.mjs → simpleEqualityMatcher-DOJhwQ8g.mjs} +2 -3
- package/dist/{sse-CuNNWr2z.mjs → sse-2972pVwV.mjs} +8 -9
- package/dist/{sseStream-C_2ujAVY.mjs → sseStream-AWLEeNV-.mjs} +3 -4
- package/dist/{storage-Cx9Sz3Ou.d.mts → storage-odC5MNKN.d.mts} +0 -2
- package/dist/{store-helpers-C8uBGCbb.mjs → store-helpers-VzjgVTkM.mjs} +2 -3
- package/dist/{streaming-Bdq_M4d5.mjs → streaming-DvraWW6x.mjs} +2 -3
- package/dist/{subscriberIdentity-B-KpZkdl.mjs → subscriberIdentity-Bya56jsg.mjs} +2 -3
- package/dist/{tenancy-C5PCvm1h.mjs → tenancy-DSa_0hhw.mjs} +3 -4
- package/dist/{tenantPreparation-dYvWrgNa.mjs → tenantPreparation-BrpkQre3.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-6rQTuCwg.mjs} +3 -5
- package/dist/{tracing-Dro5eH6j.d.mts → tracing-JSFiBl5r.d.mts} +0 -2
- package/dist/{transactionContext-DrcNyjpv.mjs → transactionContext-DaxYUEgH.mjs} +2 -3
- package/dist/{typeGuards-CEl10KPy.mjs → typeGuards-UKnX8wPX.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-D3Ixsh00.d.mts → types-BYEb_dLW.d.mts} +2 -4
- 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-CuGjhn83.mjs} +5 -6
- 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-oX5_mOVs.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-CjjGOT4E.mjs} +20 -30
- package/dist/{validate-D_mdOCir.mjs → validate-4RlTKOJb.mjs} +5 -7
- package/dist/{versioning-DBGHjPh7.mjs → versioning-Dk2-19La.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-DoBsoVo4.mjs} +3 -4
- package/llms.txt +37 -30
- package/package.json +9 -8
- 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
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# Production: boot, runtime, roles, deployment
|
|
2
|
+
|
|
3
|
+
## Production createApp
|
|
4
|
+
|
|
5
|
+
```typescript
|
|
6
|
+
import { createApp } from '@classytic/arc/factory';
|
|
7
|
+
|
|
8
|
+
if (!process.env.JWT_SECRET || process.env.JWT_SECRET.length < 32) throw new Error('JWT_SECRET');
|
|
9
|
+
if (!process.env.ALLOWED_ORIGINS) throw new Error('ALLOWED_ORIGINS');
|
|
10
|
+
|
|
11
|
+
const app = await createApp({
|
|
12
|
+
preset: 'production',
|
|
13
|
+
runtime: 'memory', // REQUIRED with preset 'production': 'memory' | 'distributed'
|
|
14
|
+
auth: { type: 'jwt', jwt: { secret: process.env.JWT_SECRET } },
|
|
15
|
+
cors: { origin: process.env.ALLOWED_ORIGINS.split(','), credentials: true },
|
|
16
|
+
rateLimit: { max: 100, timeWindow: '1 minute' },
|
|
17
|
+
trustProxy: '10.0.0.0/8', // name the proxies; default false; a hop count is not accepted
|
|
18
|
+
arcPlugins: { queryCache: true, gracefulShutdown: { drainDelayMs: 10_000 } },
|
|
19
|
+
});
|
|
20
|
+
await app.listen({ port: 3000, host: '0.0.0.0' });
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
| Option | Notes |
|
|
24
|
+
|---|---|
|
|
25
|
+
| `runtime` | `'memory'` = exactly one instance. `'distributed'` = more than one replica; audited at boot (production-distributed.md) |
|
|
26
|
+
| `trustProxy` | `true`, CIDR string/array, or `'loopback'`. Unset behind a proxy makes `request.ip` the proxy |
|
|
27
|
+
| `keepAliveTimeout` | Default 72000; keep above the LB idle timeout or you get intermittent 502 |
|
|
28
|
+
| `requestTimeout`, `connectionTimeout`, `bodyLimit`, `maxParamLength` | Fastify pass-through (body 1 MiB, param 400) |
|
|
29
|
+
| `underPressure` | Production preset sets `maxEventLoopDelay: 3000`; override `{ maxEventLoopDelay: 500 }`, disable `false` |
|
|
30
|
+
| `strictResourceDir`, `strictResources` | Throw on empty discovery or duplicate resource names; turn on in production |
|
|
31
|
+
| `resourceDir: import.meta.url` | Works from `src/` and `dist/`; a path string resolves against `process.cwd()` |
|
|
32
|
+
|
|
33
|
+
Response compression is not included: use the reverse proxy or CDN.
|
|
34
|
+
|
|
35
|
+
## Roles
|
|
36
|
+
|
|
37
|
+
`role` decides which async machinery mounts (default `'all'`).
|
|
38
|
+
|
|
39
|
+
| Role | Behavior |
|
|
40
|
+
|---|---|
|
|
41
|
+
| `api`, `worker` | No module schedule arms run (outbox relay included) |
|
|
42
|
+
| `relay` | Only `kind: 'relay'` arms run; declaring `resources` or `resourceDir` throws |
|
|
43
|
+
| `scheduler` | Every arm runs; declaring HTTP resources throws |
|
|
44
|
+
| `all` | Everything |
|
|
45
|
+
|
|
46
|
+
`createWorker` (from `@classytic/arc/factory`) and `preset: 'worker'` build headless processes: resources register without mounting routes (`mountRoutes: false`).
|
|
47
|
+
|
|
48
|
+
## Deployment
|
|
49
|
+
|
|
50
|
+
| Target | Preset | Entry |
|
|
51
|
+
|---|---|---|
|
|
52
|
+
| Docker/K8s, Cloud Run, Railway, Render, Fly | `production` | `app.listen()` |
|
|
53
|
+
| AWS Lambda, Vercel Serverless, Cloudflare Workers (`nodejs_compat`) | `edge` | `toFetchHandler(app)` |
|
|
54
|
+
|
|
55
|
+
```typescript
|
|
56
|
+
import { createApp, toFetchHandler } from '@classytic/arc/factory';
|
|
57
|
+
const app = await createApp({ preset: 'edge', auth: { type: 'jwt', jwt: { secret } } });
|
|
58
|
+
export default { fetch: toFetchHandler(app) };
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`toFetchHandler` buffers both directions: no SSE, streaming or WebSocket. Publish events to a dedicated edge tier for realtime.
|
|
62
|
+
|
|
63
|
+
## CORS
|
|
64
|
+
|
|
65
|
+
- Production without `cors.origin` warns. `origin: '*'` with `credentials: true` throws at boot; use an allow-list.
|
|
66
|
+
- 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.
|
|
67
|
+
- Mobile webviews (Capacitor, Ionic): add webview origins and expose the Better Auth bearer header.
|
|
68
|
+
|
|
69
|
+
```typescript
|
|
70
|
+
cors: {
|
|
71
|
+
origin: [...webOrigins, 'https://localhost', 'capacitor://localhost'],
|
|
72
|
+
credentials: true,
|
|
73
|
+
exposedHeaders: ['set-auth-token'], // Better Auth bearer plugin; without it JS cannot read the token
|
|
74
|
+
},
|
|
75
|
+
trustProxy: true,
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Add the same origins to Better Auth `trustedOrigins`. Native HTTP clients send no `Origin`; CORS does not apply.
|
|
79
|
+
|
|
80
|
+
## Security defaults
|
|
81
|
+
|
|
82
|
+
- Field-write permission denial rejects with 403 listing denied fields; `onFieldWriteDenied: 'strip'` per resource silently drops instead.
|
|
83
|
+
- Scope elevation always emits `arc.scope.elevated`: `fastify.events.subscribe('arc.scope.elevated', handler)`.
|
|
84
|
+
- `multiTenant` injects the caller's org on update, overwriting a body-supplied `organizationId`.
|
|
85
|
+
- `verifySignature(body, secret, sig)` throws `TypeError` unless body is a string or Buffer: register `@fastify/raw-body` and pass `req.rawBody`.
|
|
86
|
+
- Upload preset `sanitizeFilename` is strict by default; relax per adapter with `false`, `'*'` or a function.
|
|
87
|
+
- Logger redaction defaults to `DEFAULT_LOGGER_REDACT_PATHS` when you pass an object logger without `redact`.
|
|
88
|
+
|
|
89
|
+
## Multi-domain deployments
|
|
90
|
+
|
|
91
|
+
Arc owns no domain routing, certificates or wildcard hosts. Resolve a custom tenant domain at a gateway or early plugin, then authorize through the normal permission path. Never treat `Host` or `X-Forwarded-Host` as tenant authorization: it only selects a candidate, membership resolution authorizes it (same rule as `resolveOrgFromHeader`).
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Production: caching
|
|
2
|
+
|
|
3
|
+
Three independent layers. Pick one per concern.
|
|
4
|
+
|
|
5
|
+
| Layer | Enable | Scope |
|
|
6
|
+
|---|---|---|
|
|
7
|
+
| QueryCache | `arcPlugins.queryCache` plus per-resource `cache` | Server data cache with stale-while-revalidate and mutation invalidation |
|
|
8
|
+
| HTTP caching headers | `arcPlugins.caching` | ETag, `Cache-Control`, 304 |
|
|
9
|
+
| Response cache | `responseCachePlugin` | In-process LRU of GET responses, per replica |
|
|
10
|
+
|
|
11
|
+
## QueryCache
|
|
12
|
+
|
|
13
|
+
```typescript
|
|
14
|
+
const app = await createApp({
|
|
15
|
+
arcPlugins: { queryCache: true }, // memory store
|
|
16
|
+
// distributed: stores: { queryCache: new RedisCacheStore({ client: redis }) }
|
|
17
|
+
});
|
|
18
|
+
|
|
19
|
+
defineResource({
|
|
20
|
+
name: 'product',
|
|
21
|
+
cache: {
|
|
22
|
+
staleTime: 30, // seconds fresh, no revalidation (default 0)
|
|
23
|
+
gcTime: 300, // seconds stale data is kept, the SWR window (default 60)
|
|
24
|
+
tags: ['catalog'], // cross-resource group
|
|
25
|
+
invalidateOn: { 'category.*': ['catalog'] }, // event pattern to tag invalidation
|
|
26
|
+
jitter: 0.1, // spread revalidation across keys
|
|
27
|
+
},
|
|
28
|
+
});
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
- GET responses carry `x-cache: HIT | STALE | MISS`.
|
|
32
|
+
- POST, PATCH, DELETE bump the resource version and invalidate its cached queries; tags invalidate across resources.
|
|
33
|
+
- Keys are scoped by user and org, so tenants never share entries.
|
|
34
|
+
- `invalidateOn` needs `queryCachePlugin` (enabled by `arcPlugins.queryCache`); without it boot only warns and the rules are ignored.
|
|
35
|
+
- `RedisCacheStore` options: `client`, `prefix` (`arc:cache:`), `defaultTtlSeconds` (60), `maxEntryBytes`. Adapt clients with `ioredisAsCacheClient` / `upstashAsCacheClient`.
|
|
36
|
+
- Under `runtime: 'distributed'` a memory store fails the boot (production-distributed.md).
|
|
37
|
+
|
|
38
|
+
## HTTP caching headers
|
|
39
|
+
|
|
40
|
+
```typescript
|
|
41
|
+
createApp({ arcPlugins: { caching: { maxAge: 0, etag: true, conditional: true, methods: ['GET', 'HEAD'], exclude: ['/api/auth'], rules: [] } } });
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Requires `stores.cache` under `runtime: 'distributed'`.
|
|
45
|
+
|
|
46
|
+
## Response cache
|
|
47
|
+
|
|
48
|
+
```typescript
|
|
49
|
+
import { responseCachePlugin } from '@classytic/arc/plugins/response-cache';
|
|
50
|
+
|
|
51
|
+
await fastify.register(responseCachePlugin, {
|
|
52
|
+
maxEntries: 500, defaultTTL: 30,
|
|
53
|
+
rules: [{ match: '/api/products', ttl: 120 }, { match: '/api/users', ttl: 0 }],
|
|
54
|
+
exclude: ['/api/me'],
|
|
55
|
+
eventInvalidation: { patterns: { 'order.*': ['/api/products'] } },
|
|
56
|
+
xCacheHeader: true,
|
|
57
|
+
});
|
|
58
|
+
fastify.responseCache.invalidate('/api/products');
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
- Per replica by design: correctness comes from short TTLs. Declared `accepted` in the capability audit.
|
|
62
|
+
- `responseCache.middleware` must run after authentication; the default key includes user and org.
|
|
63
|
+
- Prefer QueryCache when a resource needs shared, tagged invalidation.
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
# Production: distributed runtime
|
|
2
|
+
|
|
3
|
+
`runtime: 'distributed'` is the "more than one replica" switch. Boot fails when any subsystem holds state that exists only in this process. Two checks, one policy.
|
|
4
|
+
|
|
5
|
+
## 1. Constructor guard (what `createApp` can see)
|
|
6
|
+
|
|
7
|
+
| Requirement | Applies when |
|
|
8
|
+
|---|---|
|
|
9
|
+
| `stores.events` durable transport | always |
|
|
10
|
+
| `stores.cache` | `arcPlugins.caching` enabled |
|
|
11
|
+
| `stores.queryCache` | `arcPlugins.queryCache` enabled |
|
|
12
|
+
| `stores.idempotency` | memory store is rejected; a missing one only warns |
|
|
13
|
+
| `rateLimit: { redis: client }` or `{ store }` | rate limiting on; `rateLimit: false` opts out |
|
|
14
|
+
| `arcPlugins.schedules.lock` (`LockAdapter`) or `singleReplica: true` | schedules object enabled; `singleReplica` claims exactly one replica arms schedules (the pinned `role: 'scheduler'` deployment) |
|
|
15
|
+
|
|
16
|
+
## 2. Capability audit (end of boot)
|
|
17
|
+
|
|
18
|
+
Covers everything wired in `plugins()`, `bootstrap[]` or module phases. Subsystems declare themselves; undeclared-shared memory defaults fail the boot in one error naming every violator.
|
|
19
|
+
|
|
20
|
+
| Subsystem | Memory default | Shared fix |
|
|
21
|
+
|---|---|---|
|
|
22
|
+
| `auth.sessions` | `MemorySessionStore` | `RedisSessionStore` (`@classytic/arc/auth/redis`) |
|
|
23
|
+
| `usage.store` | `MemoryUsageStore` | `RedisUsageStore` (`@classytic/arc/usage`) |
|
|
24
|
+
| `audit.store` | `MemoryAuditStore` | `auditPlugin` `repository` or `customStores` |
|
|
25
|
+
| `cache.query` | `MemoryCacheStore` | `stores.queryCache: new RedisCacheStore({ client })` (`@classytic/arc/cache`) |
|
|
26
|
+
| `permissions.dynamic-cache` | internal memory | `cacheStore` option, and pass `fastify` so the audit sees it |
|
|
27
|
+
| `websocket.adapter` | `LocalWebSocketAdapter` | `RedisWebSocketAdapter` (`@classytic/arc/integrations/websocket-redis`) |
|
|
28
|
+
| `websocket.pushref-store` | memory | `RedisPushRefStore` (`@classytic/arc/integrations/websocket-pushref-redis`) via `pushRefStore` |
|
|
29
|
+
| `webhooks.store` | `MemoryWebhookStore` | pass `store`, or `createDurableWebhookModule` |
|
|
30
|
+
| `mcp.resource-rate-limit` | memory limiter | shared `rateLimit` backend, when resources declare `rateLimit` |
|
|
31
|
+
| `http.response-cache` | memory | none: declared `accepted` (per replica by design, short TTLs). Logged, never a failure |
|
|
32
|
+
|
|
33
|
+
Events: `stores.events` with `RedisEventTransport` (`@classytic/arc/events/redis`) or `RedisStreamTransport` (`@classytic/arc/events/redis-stream`).
|
|
34
|
+
|
|
35
|
+
## Declare your own state
|
|
36
|
+
|
|
37
|
+
A replica-local cache built in `plugins()` belongs in the audit. Declare from anywhere a registration reaches, including your own encapsulated `fastify.register()`.
|
|
38
|
+
|
|
39
|
+
```typescript
|
|
40
|
+
import { declareRuntimeCapability } from '@classytic/arc/utils';
|
|
41
|
+
|
|
42
|
+
declareRuntimeCapability(fastify, {
|
|
43
|
+
subsystem: 'billing.sequence-cache',
|
|
44
|
+
durability: 'memory', // 'memory' | 'shared'
|
|
45
|
+
detail: 'invoice numbering cached per process',
|
|
46
|
+
// accepted: true, // only when per-process is intended
|
|
47
|
+
});
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
`accepted: true` must be stated by the declarant, never inferred.
|
|
51
|
+
|
|
52
|
+
## Circuit breakers count per replica
|
|
53
|
+
|
|
54
|
+
`CircuitBreaker` state is in-process: with 50 pods and `failureThreshold: 5`, a dead downstream absorbs 250 real requests. Share the failure window:
|
|
55
|
+
|
|
56
|
+
```typescript
|
|
57
|
+
import { CircuitBreaker, RedisCircuitBreakerState } from '@classytic/arc/utils';
|
|
58
|
+
|
|
59
|
+
const shared = new RedisCircuitBreakerState({ redis, windowMs: 60_000, prefix: 'arc:circuit:' });
|
|
60
|
+
|
|
61
|
+
const payments = new CircuitBreaker(charge, {
|
|
62
|
+
name: 'stripe.charges', // REQUIRED with sharedState: the key every replica counts under
|
|
63
|
+
failureThreshold: 5,
|
|
64
|
+
sharedState: shared,
|
|
65
|
+
});
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
- Shares the failure signal, not the state machine: each replica still owns its own OPEN/HALF_OPEN probing.
|
|
69
|
+
- The success path never touches the network; a throwing store degrades to local counting.
|
|
70
|
+
- `windowMs` must be positive (fixed window, default 60s).
|
|
71
|
+
|
|
72
|
+
## Gotchas
|
|
73
|
+
|
|
74
|
+
- Run migrations from one owner (deploy job) or pass a `lock`; see production-reliability.md.
|
|
75
|
+
- Relay, scheduler and worker processes: `role` in production-boot.md.
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# Production: idempotency
|
|
2
|
+
|
|
3
|
+
Replays the stored response for a repeated mutation. Disabled unless `enabled: true`. Register it after authentication so the principal and tenant isolate keys.
|
|
4
|
+
|
|
5
|
+
```typescript
|
|
6
|
+
import { idempotencyPlugin } from '@classytic/arc/idempotency';
|
|
7
|
+
|
|
8
|
+
await fastify.register(idempotencyPlugin, {
|
|
9
|
+
enabled: true,
|
|
10
|
+
headerName: 'idempotency-key', // default
|
|
11
|
+
ttlMs: 86_400_000, // cached response lifetime, default 24h
|
|
12
|
+
lockTimeoutMs: 30_000, // in-flight lease, default 30s
|
|
13
|
+
methods: ['POST', 'PUT', 'PATCH'],
|
|
14
|
+
include: [/\/orders/], // regex allowlist (optional)
|
|
15
|
+
exclude: [/\/health/], // wins over include
|
|
16
|
+
retryAfterSeconds: 1,
|
|
17
|
+
namespace: 'api', // fold into the fingerprint when deployments share one store
|
|
18
|
+
});
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
| Case | Result |
|
|
22
|
+
|---|---|
|
|
23
|
+
| First request | Runs, stores the response |
|
|
24
|
+
| Retry, same key and body | Stored response, header `x-idempotency-replayed: true` |
|
|
25
|
+
| Same key, different body | 422 (fingerprint mismatch) |
|
|
26
|
+
| Concurrent, first still running | 409 with `Retry-After` |
|
|
27
|
+
| Key required but missing | 400 `arc.idempotency_key_required` |
|
|
28
|
+
|
|
29
|
+
```typescript
|
|
30
|
+
fetch('/api/orders', { method: 'POST', headers: { 'Idempotency-Key': crypto.randomUUID() }, body });
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Require a key
|
|
34
|
+
|
|
35
|
+
```typescript
|
|
36
|
+
defineResource({ name: 'order', idempotency: { required: ['create', 'update'] } }); // built-in write routes
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Boot fails when a listed op is not mounted or the plugin is disabled. Custom routes:
|
|
40
|
+
|
|
41
|
+
```typescript
|
|
42
|
+
routes: [{
|
|
43
|
+
method: 'POST', path: '/:id/charge', handler: 'charge',
|
|
44
|
+
config: { idempotency: { required: true } }, // any method, DELETE included
|
|
45
|
+
}]
|
|
46
|
+
// action routes: { requiredActions: ['refund'] }
|
|
47
|
+
// handler owns at-most-once: { required: true, dedup: 'handler', owner: 'payments-runner' }
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
`dedup: 'handler'` still demands the key and exposes `request.idempotencyKey`, but stores and replays nothing. A custom route using `fastify.idempotency.middleware` in its own `preHandler` must place it after `fastify.authenticate`.
|
|
51
|
+
|
|
52
|
+
## Stores
|
|
53
|
+
|
|
54
|
+
```typescript
|
|
55
|
+
// Memory (default; dev, single instance): omit repository and store.
|
|
56
|
+
|
|
57
|
+
// Redis (multi-instance)
|
|
58
|
+
import { RedisIdempotencyStore } from '@classytic/arc/idempotency/redis';
|
|
59
|
+
store: new RedisIdempotencyStore({ client: redis, prefix: 'idem:', ttlMs: 86_400_000 })
|
|
60
|
+
// ioredisAsIdempotencyClient / upstashAsIdempotencyClient adapt other clients
|
|
61
|
+
|
|
62
|
+
// Database via any RepositoryLike (needs getOne, deleteMany, findOneAndUpdate)
|
|
63
|
+
import { Repository, methodRegistryPlugin, batchOperationsPlugin, mongoOperationsPlugin } from '@classytic/mongokit';
|
|
64
|
+
const IdempotencyModel = mongoose.model(
|
|
65
|
+
'IdempotencyKey',
|
|
66
|
+
new Schema({ _id: String }, { strict: false, strictQuery: false, timestamps: false }),
|
|
67
|
+
);
|
|
68
|
+
repository: new Repository(IdempotencyModel, [methodRegistryPlugin(), batchOperationsPlugin(), mongoOperationsPlugin()])
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
- The schema must declare `_id: String` and `strictQuery: false`. A pathless schema under global `strictQuery: true` strips the key filter and replays one cached response to every key and user. A boot self-check (`selfCheck`, default on) refuses such a store.
|
|
72
|
+
- `repository` takes precedence over `store`. Arc closes only stores it built.
|
|
73
|
+
- With `createApp({ runtime: 'distributed' })`, pass `stores.idempotency`; a memory store is rejected.
|
|
74
|
+
|
|
75
|
+
## IdempotencyStore contract
|
|
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 without fencing needs `allowUnfencedCompletion: true`.
|
|
78
|
+
|
|
79
|
+
## Gotchas
|
|
80
|
+
|
|
81
|
+
- A crash between the business write and completion, or a handler outliving its lease, can repeat effects: use `dedup: 'handler'` with a shared transaction or a unique constraint when replay protection alone is not enough.
|
|
82
|
+
- Utilities: `fastify.idempotency.invalidate(key)`, `.has(key)`, `.store`.
|
|
83
|
+
- MCP mutating tools accept `_idempotencyKey` against the same store (mcp-setup.md).
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# Production: health, request id, metrics, tracing
|
|
2
|
+
|
|
3
|
+
`createApp` registers request id, health and graceful shutdown by default; metrics and versioning are opt-in under `arcPlugins`.
|
|
4
|
+
|
|
5
|
+
## Health
|
|
6
|
+
|
|
7
|
+
```typescript
|
|
8
|
+
const app = await createApp({
|
|
9
|
+
arcPlugins: {
|
|
10
|
+
health: {
|
|
11
|
+
prefix: '/_health',
|
|
12
|
+
version: '1.0.0',
|
|
13
|
+
checks: [
|
|
14
|
+
{ name: 'mongo', check: () => mongoose.connection.readyState === 1 },
|
|
15
|
+
{ name: 'redis', check: async () => (await redis.ping()) === 'PONG', timeout: 3000 },
|
|
16
|
+
{ name: 'search', check: async () => search.isReady(), critical: false },
|
|
17
|
+
],
|
|
18
|
+
},
|
|
19
|
+
},
|
|
20
|
+
});
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Manual: `fastify.register(healthPlugin, opts)` from `@classytic/arc/plugins`; `checks` run with an `AbortSignal`.
|
|
24
|
+
|
|
25
|
+
| Route | Response |
|
|
26
|
+
|---|---|
|
|
27
|
+
| `GET /_health` and `/_health/live` | 200 `{ status: 'ok', timestamp, version? }` |
|
|
28
|
+
| `GET /_health/ready` | 200 `{ status: 'ready', timestamp, checks: [{ name, healthy, duration, error? }] }` |
|
|
29
|
+
| ready, critical check failed | 503 `status: 'not_ready'` |
|
|
30
|
+
| ready, shutdown draining | 503 `status: 'draining'` (liveness stays 200) |
|
|
31
|
+
|
|
32
|
+
- `critical` defaults to true; only critical failures return 503.
|
|
33
|
+
- Health-check names must be unique across the app (duplicates throw at boot).
|
|
34
|
+
- `metrics: true` adds `/_health/metrics` with process metrics; `metricsCollector` replaces the body.
|
|
35
|
+
|
|
36
|
+
## Request id
|
|
37
|
+
|
|
38
|
+
```typescript
|
|
39
|
+
import { requestIdPlugin } from '@classytic/arc/plugins';
|
|
40
|
+
await fastify.register(requestIdPlugin, { header: 'x-request-id', setResponseHeader: true, generator: () => crypto.randomUUID() });
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Incoming ids are sanitized (max 128 chars, safe charset; repeated headers rejected). The id is echoed on the response and carried in logs.
|
|
44
|
+
|
|
45
|
+
## Metrics
|
|
46
|
+
|
|
47
|
+
```typescript
|
|
48
|
+
const app = await createApp({ arcPlugins: { metrics: { path: '/_metrics', prefix: 'arc', maxSeries: 1000, onCollect: (m) => pushToOtlp(m) } } });
|
|
49
|
+
// GET /_metrics: Prometheus text
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
| Series (prefix `arc`) | Type |
|
|
53
|
+
|---|---|
|
|
54
|
+
| `arc_http_requests_total`, `arc_http_request_duration_seconds` | HTTP by method, route, status |
|
|
55
|
+
| `arc_crud_operations_total`, `arc_crud_operation_duration_seconds` | CRUD |
|
|
56
|
+
| `arc_cache_hits_total`, `arc_cache_misses_total` | cache |
|
|
57
|
+
| `arc_events_published_total`, `arc_events_consumed_total` | events |
|
|
58
|
+
| `arc_circuit_breaker_state` | breakers |
|
|
59
|
+
|
|
60
|
+
Programmatic: `fastify.metrics.recordOperation(resource, op, status, durationMs)`, `.recordCacheHit(resource)`, `.recordEventPublish(type)`, `.collect()`, `.reset()`. `maxSeries` bounds label cardinality per metric.
|
|
61
|
+
|
|
62
|
+
## Tracing (OpenTelemetry)
|
|
63
|
+
|
|
64
|
+
Needs `@opentelemetry/api` plus the SDK and OTLP exporter packages; without them tracing is a no-op (`isTracingAvailable()`).
|
|
65
|
+
|
|
66
|
+
```typescript
|
|
67
|
+
import { tracingPlugin, createSpan, traced } from '@classytic/arc/plugins/tracing';
|
|
68
|
+
|
|
69
|
+
await fastify.register(tracingPlugin, {
|
|
70
|
+
serviceName: 'my-api',
|
|
71
|
+
exporterUrl: 'http://localhost:4318/v1/traces', // default
|
|
72
|
+
sampleRate: 0.1, // default 1.0
|
|
73
|
+
autoInstrumentation: true,
|
|
74
|
+
});
|
|
75
|
+
|
|
76
|
+
// Custom span; span is null when tracing is off
|
|
77
|
+
return createSpan(req, 'processPayment', async (span) => {
|
|
78
|
+
span?.setAttribute('orderId', order.id);
|
|
79
|
+
return processPayment(order);
|
|
80
|
+
});
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
`traced(spanName?)` decorates a method that receives the request as an argument. Use `getTraceHeaders` from `@classytic/arc/context` to propagate trace context into outbox rows.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Production: SSE, realtime change feed, streaming routes
|
|
2
|
+
|
|
3
|
+
Pick by need:
|
|
4
|
+
|
|
5
|
+
| Need | Use |
|
|
6
|
+
|---|---|
|
|
7
|
+
| Per-user live views of a resource (list permission, row filter, field masking) | `arcPlugins.realtime` |
|
|
8
|
+
| Raw domain-event firehose | `arcPlugins.sse` |
|
|
9
|
+
| Bidirectional or geo rooms | `integrations/websocket` (its CRUD bridge is org-coarse: never expose row-permissioned resources through it) |
|
|
10
|
+
| Massive fan-out (viral feeds, live scores) | Publish once via `app.events.subscribe(...)` to a dedicated edge fan-out tier |
|
|
11
|
+
|
|
12
|
+
Both feeds need the event plugin (on by default).
|
|
13
|
+
|
|
14
|
+
## Realtime change feed
|
|
15
|
+
|
|
16
|
+
```typescript
|
|
17
|
+
const app = await createApp({
|
|
18
|
+
arcPlugins: { realtime: { path: '/realtime/:resource', heartbeat: 30_000, resources: ['order'], maxConnectionMs: 30 * 60_000 } },
|
|
19
|
+
});
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
- `GET /realtime/:resource` (resource name) and multiplexed `GET /realtime?resources=a,b,c` (max 20).
|
|
23
|
+
- Gated by the resource's own `list` permission; per-event row filtering, tenant guard, field masking.
|
|
24
|
+
- Client: plain `EventSource` with `?token=` (`tokenQueryParam`, default `token`, `null` disables).
|
|
25
|
+
- No replay: on reconnect, refetch the list.
|
|
26
|
+
- Permission filters are snapshotted at connect. The feed closes at token `exp` and at `maxConnectionMs` (default 30 min) to bound staleness.
|
|
27
|
+
|
|
28
|
+
## SSE plugin
|
|
29
|
+
|
|
30
|
+
```typescript
|
|
31
|
+
const app = await createApp({
|
|
32
|
+
arcPlugins: {
|
|
33
|
+
sse: {
|
|
34
|
+
path: '/events/stream', // default
|
|
35
|
+
requireAuth: true, // default; throws at registration if fastify.authenticate is missing
|
|
36
|
+
patterns: ['order.*', 'product.*'],// default ['*']
|
|
37
|
+
orgScoped: true, // default: events with organizationId reach only that org
|
|
38
|
+
heartbeat: 30_000,
|
|
39
|
+
filter: (event, request) => true,
|
|
40
|
+
audience: (event) => [(event.payload as { ownerId: string }).ownerId], // keyed delivery; connections key on scope user id
|
|
41
|
+
},
|
|
42
|
+
},
|
|
43
|
+
});
|
|
44
|
+
// Manual: import { ssePlugin } from '@classytic/arc/plugins';
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
- Events without `organizationId` reach every caller. An elevated admin with no active org sees all tenants.
|
|
48
|
+
- `orgScoped: false` only for a deliberately cross-tenant stream; keep `requireAuth` and add a `filter`.
|
|
49
|
+
- `fastify.sseStats()` returns `{ connections, keys }`.
|
|
50
|
+
|
|
51
|
+
## Streaming custom routes
|
|
52
|
+
|
|
53
|
+
```typescript
|
|
54
|
+
import { requireAuth } from '@classytic/arc/permissions';
|
|
55
|
+
import { pipeUIMessageStreamToReply } from '@classytic/arc/utils';
|
|
56
|
+
|
|
57
|
+
routes: [{
|
|
58
|
+
method: 'POST', path: '/chat',
|
|
59
|
+
streamResponse: true, // SSE headers, bypasses response serialization
|
|
60
|
+
permissions: requireAuth(),
|
|
61
|
+
preAuth: [(req) => { const t = (req.query as { token?: string }).token; if (t) req.headers.authorization = `Bearer ${t}`; }],
|
|
62
|
+
handler: async (req, reply) => {
|
|
63
|
+
await pipeUIMessageStreamToReply(reply, result.toUIMessageStream());
|
|
64
|
+
},
|
|
65
|
+
}]
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
- `preAuth` handlers run before authentication; use them to promote `?token=` because `EventSource` cannot set headers. `promoteStreamTokenToHeader(request, 'token')` from `@classytic/arc/utils` does this safely (no-op when `Authorization` exists, token still fully authenticated).
|
|
69
|
+
- `openSseStream` (utils) takes over the socket after every gate has passed; no JSON error can be sent afterwards.
|
|
70
|
+
- Edge `toFetchHandler` cannot stream.
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
# Production: outbox, compensation, migrations
|
|
2
|
+
|
|
3
|
+
## Event outbox
|
|
4
|
+
|
|
5
|
+
At-least-once delivery even when the transport is down. Prefer the module form: it owns the relay schedule, shutdown and a readiness check.
|
|
6
|
+
|
|
7
|
+
```typescript
|
|
8
|
+
import { createOutboxModule, exponentialBackoff, repositoryAsOutboxStore } from '@classytic/arc/events';
|
|
9
|
+
import { Repository } from '@classytic/mongokit';
|
|
10
|
+
|
|
11
|
+
const outbox = createOutboxModule({
|
|
12
|
+
store: repositoryAsOutboxStore(new Repository(OutboxModel)),
|
|
13
|
+
relayEveryMs: 5000, // default
|
|
14
|
+
failurePolicy: ({ attempts }) =>
|
|
15
|
+
attempts >= 5 ? { deadLetter: true } : { retryAt: exponentialBackoff({ attempt: attempts }) },
|
|
16
|
+
health: { relayLagUnhealthyMs: 5 * 60_000, probeCacheMs: 5000 },
|
|
17
|
+
});
|
|
18
|
+
|
|
19
|
+
const app = await createApp({ modules: [outbox, orderModule] }); // consumers declare dependsOn: ['outbox']
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Writers use the module exports (`getModuleExports<OutboxModuleExports>(f, 'outbox')` from `@classytic/arc/factory`):
|
|
23
|
+
|
|
24
|
+
| Export | Use |
|
|
25
|
+
|---|---|
|
|
26
|
+
| `store` | Write events: `await store.save(event)`. Joins the active transaction automatically (`sessionProvider` defaults to `transactionContext.get()`), so the row commits with the domain write |
|
|
27
|
+
| `requestDrain()` | Nudge a relay pass after commit (milliseconds, not `relayEveryMs`); coalesced; never throws |
|
|
28
|
+
| `drain({ maxPasses })` | Await delivery including cascades; for tests and shutdown |
|
|
29
|
+
| `health()` | Same reading as the readiness check |
|
|
30
|
+
| `relay` | The `EventOutbox` |
|
|
31
|
+
|
|
32
|
+
- Always set a `failurePolicy`. Without one a failing row stays pending and is retried every poll forever, logging per event. `attempts` is the durable count and survives restarts.
|
|
33
|
+
- Readiness check `<name>.relay` is non-critical (pulling a pod does not drain the relay). Unhealthy on any dead letter or pending lag past `relayLagUnhealthyMs`; `alertEveryMs` also logs `OUTBOX_RELAY_LAG` / `OUTBOX_DEAD_LETTER`.
|
|
34
|
+
- `transport` defaults to the app's own event transport; `consumerId` defaults to a per-instance id and must stay unique per relay.
|
|
35
|
+
- Under `role: 'api'` or `'worker'` the relay arm does not run; run it in a `role: 'relay'` process.
|
|
36
|
+
- Store contract (`@classytic/primitives/outbox`): required `save`, `getPending`, `acknowledge`; optional `claimPending`, `claimPendingFenced`, `fail`, `getDeadLettered`, `requeue`, `purge`, `countByStatus`, `oldestPendingAgeMs`. Prove a custom store with `runOutboxStoreContract` from `@classytic/arc/testing/outbox`.
|
|
37
|
+
|
|
38
|
+
Hand-wired form (tests, custom scheduling):
|
|
39
|
+
|
|
40
|
+
```typescript
|
|
41
|
+
import { EventOutbox, MemoryOutboxStore } from '@classytic/arc/events';
|
|
42
|
+
|
|
43
|
+
const relay = new EventOutbox({ store: new MemoryOutboxStore(), transport, batchSize: 100, failurePolicy });
|
|
44
|
+
// or { repository: new Repository(OutboxModel), transport }
|
|
45
|
+
await relay.store(event, { session });
|
|
46
|
+
await relay.relay(); // publishes pending to the transport
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Compensating transactions
|
|
50
|
+
|
|
51
|
+
In-process rollback: steps run in order, completed steps compensate in reverse on failure. A process crash skips compensation; for durable distributed workflows use `@classytic/streamline` or a workflow engine.
|
|
52
|
+
|
|
53
|
+
```typescript
|
|
54
|
+
import { withCompensation, defineCompensation } from '@classytic/arc/utils';
|
|
55
|
+
|
|
56
|
+
const result = await withCompensation('place-order', [
|
|
57
|
+
{
|
|
58
|
+
name: 'reserve-inventory',
|
|
59
|
+
execute: async (ctx) => { const r = await inventory.reserve(ctx.items); ctx.reservationId = r.id; return r; },
|
|
60
|
+
compensate: async (_ctx, r) => { await inventory.release(r.id); },
|
|
61
|
+
},
|
|
62
|
+
{ name: 'charge', execute: async (ctx) => payments.charge(ctx.total), compensate: async (_c, r) => payments.refund(r.chargeId) },
|
|
63
|
+
{ name: 'email', execute: async (ctx) => mailer.send(ctx.email), fireAndForget: true },
|
|
64
|
+
], { items, total, email }, {
|
|
65
|
+
onStepComplete: (step, res) => {}, onStepFailed: (step, err) => {}, onCompensate: (step) => {}, onHookError: (hook, err) => {},
|
|
66
|
+
});
|
|
67
|
+
|
|
68
|
+
if (!result.success) { /* result.failedStep, result.error, result.compensationErrors */ }
|
|
69
|
+
const placeOrder = defineCompensation('place-order', steps); // reusable: placeOrder.execute(ctx, hooks)
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
- The context is a mutable copy shared by all steps.
|
|
73
|
+
- `fireAndForget` steps do not block, are not compensated, and appear only via `onStepFailed` on error; put must-survive side effects in the outbox.
|
|
74
|
+
- Compensation errors are collected in `result.compensationErrors` and never stop the rollback.
|
|
75
|
+
- Result is a union: `success: true` has `completedSteps` and `results`; `success: false` adds `failedStep`, `error`.
|
|
76
|
+
|
|
77
|
+
## Migrations
|
|
78
|
+
|
|
79
|
+
```typescript
|
|
80
|
+
import { defineMigration, MigrationRunner, MongoMigrationStore } from '@classytic/arc/migrations';
|
|
81
|
+
|
|
82
|
+
const v2 = defineMigration({
|
|
83
|
+
version: 2,
|
|
84
|
+
resource: 'product',
|
|
85
|
+
description: 'rename oldField',
|
|
86
|
+
up: async (db) => { await (db as mongo.Db).collection('products').updateMany({}, { $rename: { oldField: 'newField' } }); },
|
|
87
|
+
down: async (db) => { await (db as mongo.Db).collection('products').updateMany({}, { $rename: { newField: 'oldField' } }); },
|
|
88
|
+
});
|
|
89
|
+
|
|
90
|
+
const runner = new MigrationRunner(mongoose.connection.db, {
|
|
91
|
+
store: new MongoMigrationStore(mongoose.connection.db), // required
|
|
92
|
+
lock, // LockAdapter: concurrent runners fail fast
|
|
93
|
+
checksumMismatch: 'error', // default 'warn'
|
|
94
|
+
});
|
|
95
|
+
await runner.up([v2]);
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
- Run migrations from one owner (deploy job or leader), not every replica at startup.
|
|
99
|
+
- Write migrations idempotently: a crash between `up()` and recording re-runs that migration.
|
|
100
|
+
- `runner.down(...)` and `runner.downTo(...)` roll back; `computeMigrationChecksum` detects edits to applied migrations.
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# Production: graceful shutdown
|
|
2
|
+
|
|
3
|
+
Registered by default (`arcPlugins.gracefulShutdown`). Configure inline from `createApp`, or register `gracefulShutdownPlugin` from `@classytic/arc/plugins`.
|
|
4
|
+
|
|
5
|
+
```typescript
|
|
6
|
+
const app = await createApp({
|
|
7
|
+
arcPlugins: {
|
|
8
|
+
gracefulShutdown: {
|
|
9
|
+
timeout: 30_000, // hard cap; drainDelayMs counts against it
|
|
10
|
+
drainDelayMs: 10_000, // lame-duck window, default 0
|
|
11
|
+
signals: ['SIGTERM', 'SIGINT'],
|
|
12
|
+
logEvents: true,
|
|
13
|
+
onShutdown: async () => {
|
|
14
|
+
await mongoose.disconnect();
|
|
15
|
+
await redis.quit();
|
|
16
|
+
},
|
|
17
|
+
onForceExit: (reason) => process.exit(1), // reason: 'timeout' | 'error'; stub it in tests
|
|
18
|
+
},
|
|
19
|
+
},
|
|
20
|
+
});
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Sequence
|
|
24
|
+
|
|
25
|
+
1. Signal arrives: `fastify.shutdownState.draining = true`; `/_health/ready` returns 503 `draining`.
|
|
26
|
+
2. Wait `drainDelayMs`, still serving everything routed here. `/_health/live` stays 200.
|
|
27
|
+
3. `fastify.close()`: stop accepting, drain in-flight requests.
|
|
28
|
+
4. `onShutdown()`: release what arc does not own (DB connections, your Redis client).
|
|
29
|
+
5. Exit naturally; `onForceExit` fires if `timeout` elapses or a step throws.
|
|
30
|
+
|
|
31
|
+
## Rolling-deploy 502
|
|
32
|
+
|
|
33
|
+
With `drainDelayMs: 0` the instance closes the moment SIGTERM arrives, while the load balancer keeps routing to it until its readiness probe has failed for several intervals.
|
|
34
|
+
|
|
35
|
+
- Set `drainDelayMs` above the LB deregistration window, typically 5000 to 15000 ms.
|
|
36
|
+
- Kubernetes: keep `terminationGracePeriodSeconds` greater than `drainDelayMs + timeout`, or the kubelet SIGKILLs mid-drain.
|
|
37
|
+
- Liveness must not fail while draining: a 503 there gets the pod killed instead of drained.
|
|
38
|
+
|
|
39
|
+
## Gotchas
|
|
40
|
+
|
|
41
|
+
- `fastify.close()` runs before `onShutdown`: do not close anything an in-flight request still needs from `onShutdown`.
|
|
42
|
+
- Do not add `process.on('SIGTERM', () => app.close())`. The plugin owns the signals; a second handler closes immediately and skips the drain.
|
|
43
|
+
- Stores and clients you pass into arc are yours to close (in `onShutdown`).
|