@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
|
@@ -1,491 +1,126 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Events: bus, transports, handlers
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
`createApp()` registers `eventPlugin` and decorates `app.events`. Event contract types and helpers come from `@classytic/primitives/events`; arc ships the runtime.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
| Purpose | Internal lifecycle callbacks | External integration |
|
|
10
|
-
| Scope | Same process, synchronous flow | Cross-service, async |
|
|
11
|
-
| Use when | Validating, transforming, auditing | Notifying services, event-driven systems |
|
|
12
|
-
| Transport | In-process only | Pluggable (Memory → Redis → Kafka) |
|
|
13
|
-
| Pattern | `beforeCreate`, `afterUpdate` | `product.created`, `order.updated` |
|
|
5
|
+
```typescript
|
|
6
|
+
import type { EventMeta, DomainEvent, EventHandler, EventTransport, DeadLetteredEvent } from '@classytic/primitives/events';
|
|
7
|
+
import { createEvent, createChildEvent, matchEventPattern } from '@classytic/primitives/events';
|
|
8
|
+
```
|
|
14
9
|
|
|
15
10
|
## Setup
|
|
16
11
|
|
|
17
|
-
The `createApp()` factory auto-registers `eventPlugin` — no manual registration needed:
|
|
18
|
-
|
|
19
12
|
```typescript
|
|
20
13
|
import { createApp } from '@classytic/arc/factory';
|
|
21
|
-
|
|
22
|
-
// Development (in-memory, default — zero config)
|
|
23
|
-
const app = await createApp({ preset: 'development' });
|
|
24
|
-
// app.events is ready to use
|
|
25
|
-
|
|
26
|
-
// Production (Redis transport, with retry)
|
|
27
|
-
import { RedisEventTransport } from '@classytic/arc/events/redis';
|
|
14
|
+
import { RedisStreamTransport } from '@classytic/arc/events/redis-stream';
|
|
28
15
|
|
|
29
16
|
const app = await createApp({
|
|
30
|
-
stores: { events: new
|
|
17
|
+
stores: { events: new RedisStreamTransport(redis, { stream: 'arc:events', group: 'api', consumer: 'api-1' }) },
|
|
31
18
|
arcPlugins: {
|
|
32
19
|
events: {
|
|
33
|
-
|
|
34
|
-
failOpen: true, // default: suppress transport failures
|
|
20
|
+
failOpen: true, // default: publish errors are logged, not thrown
|
|
35
21
|
retry: { maxRetries: 3, backoffMs: 1000 },
|
|
22
|
+
logEvents: true,
|
|
36
23
|
},
|
|
37
24
|
},
|
|
38
25
|
});
|
|
39
|
-
|
|
40
|
-
// Disable event plugin entirely
|
|
41
|
-
const app = await createApp({ arcPlugins: { events: false } });
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
**Manual registration** (for apps not using `createApp`):
|
|
45
|
-
|
|
46
|
-
```typescript
|
|
47
|
-
import { eventPlugin } from '@classytic/arc/events';
|
|
48
|
-
|
|
49
|
-
await fastify.register(eventPlugin); // Memory transport
|
|
50
|
-
|
|
51
|
-
// Redis Pub/Sub
|
|
52
|
-
import { RedisEventTransport } from '@classytic/arc/events/redis';
|
|
53
|
-
await fastify.register(eventPlugin, {
|
|
54
|
-
transport: new RedisEventTransport(redisClient, { channel: 'arc-events' }),
|
|
55
|
-
logEvents: true,
|
|
56
|
-
});
|
|
57
|
-
|
|
58
|
-
// Redis Streams (ordered, persistent, consumer groups)
|
|
59
|
-
import { RedisStreamTransport } from '@classytic/arc/events/redis-stream';
|
|
60
|
-
await fastify.register(eventPlugin, {
|
|
61
|
-
transport: new RedisStreamTransport(redisClient, {
|
|
62
|
-
stream: 'arc:events',
|
|
63
|
-
group: 'api-service',
|
|
64
|
-
consumer: 'worker-1',
|
|
65
|
-
}),
|
|
66
|
-
});
|
|
26
|
+
await createApp({ arcPlugins: { events: false } }); // disable
|
|
67
27
|
```
|
|
68
28
|
|
|
69
|
-
`
|
|
70
|
-
- `true` (default): publish/subscribe/close transport errors are logged and suppressed.
|
|
71
|
-
- `false`: transport errors are thrown to caller.
|
|
72
|
-
|
|
73
|
-
## Auto-Emitted Events
|
|
74
|
-
|
|
75
|
-
BaseController automatically emits events when eventPlugin is registered:
|
|
29
|
+
Without `createApp`: `await fastify.register(eventPlugin, { transport })` from `@classytic/arc/events`.
|
|
76
30
|
|
|
77
|
-
|
|
|
78
|
-
|
|
79
|
-
| `
|
|
80
|
-
| `
|
|
81
|
-
| `
|
|
82
|
-
| `
|
|
31
|
+
| `eventPlugin` option | Meaning |
|
|
32
|
+
|---|---|
|
|
33
|
+
| `transport` | Default `MemoryEventTransport`. arc closes only a transport it built |
|
|
34
|
+
| `memoryTransport` | `{ logger, onHandlerError: 'log'\|'throw', handlerDispatch: 'sequential'\|'parallel' }` for the default transport |
|
|
35
|
+
| `singleProcess` | Declare one-process topology on purpose (silences the memory-transport warning) |
|
|
36
|
+
| `failOpen` | `true` (default) suppress transport errors; `false` throw to caller |
|
|
37
|
+
| `retry` / `deadLetterQueue` | Auto-wrap subscribers with `withRetry`; DLQ needs `retry`, default sink publishes `$deadLetter` |
|
|
38
|
+
| `registry`, `validateMode` | Payload validation on publish: `'warn'` (default with registry) \| `'reject'` \| `'off'` |
|
|
39
|
+
| `onPublish`, `onPublishError` | Telemetry callbacks (isolated, never affect delivery) |
|
|
40
|
+
| `warnOnDuplicate` | Dual-publish detector, on outside production |
|
|
41
|
+
| `wal` | Low-level hook; not at-least-once. Use the outbox |
|
|
83
42
|
|
|
84
|
-
|
|
43
|
+
CRUD events auto-emit on `arcPlugins.emitEvents` (default true) as `<resource>.created|updated|deleted` with payload `{ resource, operation, data, userId?, organizationId?, timestamp }`. Build names with `crudEventType('product', 'created')`. Lifecycle names: `ARC_LIFECYCLE_EVENTS`.
|
|
85
44
|
|
|
86
|
-
##
|
|
45
|
+
## Publish and subscribe
|
|
87
46
|
|
|
88
47
|
```typescript
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
orderId: 'order-123',
|
|
92
|
-
total: 99.99,
|
|
93
|
-
}, {
|
|
94
|
-
userId: request.user._id,
|
|
95
|
-
organizationId: getOrgId(request.scope),
|
|
96
|
-
correlationId: request.id,
|
|
97
|
-
});
|
|
98
|
-
|
|
99
|
-
// Subscribe to specific event
|
|
100
|
-
await fastify.events.subscribe('order.created', async (event) => {
|
|
101
|
-
await sendConfirmation(event.payload);
|
|
48
|
+
await app.events.publish('order.placed', { orderId: 'o1' }, {
|
|
49
|
+
correlationId: req.id, organizationId: getOrgId(req.scope),
|
|
102
50
|
});
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
await updateAnalytics(event.type, event.payload);
|
|
107
|
-
});
|
|
108
|
-
|
|
109
|
-
// Subscribe to all
|
|
110
|
-
await fastify.events.subscribe('*', async (event) => {
|
|
111
|
-
await auditLog.create(event);
|
|
112
|
-
});
|
|
113
|
-
|
|
114
|
-
// Unsubscribe
|
|
115
|
-
const unsub = await fastify.events.subscribe('order.created', handler);
|
|
116
|
-
unsub();
|
|
51
|
+
const unsub = await app.events.subscribe('order.*', async (event) => { /* event.type, payload, meta */ });
|
|
52
|
+
await app.events.subscribe('*', audit);
|
|
53
|
+
const stop = app.events.observe((event) => metrics.inc(event.type)); // read-only tap, also sees outbox relays
|
|
117
54
|
```
|
|
118
55
|
|
|
119
|
-
|
|
56
|
+
Patterns: exact, prefix `order.*`, global `*`. `app.events.registry?.catalog()` lists registered definitions.
|
|
120
57
|
|
|
121
|
-
|
|
58
|
+
`EventMeta`: `id`, `timestamp`, `schemaVersion?`, `correlationId?`, `causationId?`, `partitionKey?`, `source?`, `idempotencyKey?`, `resource?`, `resourceId?`, `userId?`, `organizationId?`, `aggregate?: { type, id }`.
|
|
122
59
|
|
|
123
60
|
```typescript
|
|
124
|
-
|
|
125
|
-
id: string; // UUID v4 (fresh per emit; a retry gets a new id)
|
|
126
|
-
timestamp: Date;
|
|
127
|
-
schemaVersion?: number; // bump on payload breaking change
|
|
128
|
-
correlationId?: string; // stable across causal chain
|
|
129
|
-
causationId?: string; // direct parent event id
|
|
130
|
-
partitionKey?: string; // ordering hint (Kafka/Kinesis/Streams)
|
|
131
|
-
source?: string; // originating service/package ('commerce', 'billing')
|
|
132
|
-
idempotencyKey?: string; // cross-transport dedupe hint — stable per operation
|
|
133
|
-
resource?: string;
|
|
134
|
-
resourceId?: string;
|
|
135
|
-
userId?: string;
|
|
136
|
-
organizationId?: string;
|
|
137
|
-
aggregate?: { type: string; id: string }; // DDD aggregate marker
|
|
138
|
-
}
|
|
139
|
-
|
|
140
|
-
interface DomainEvent<T> {
|
|
141
|
-
type: string; // e.g., 'order.created'
|
|
142
|
-
payload: T;
|
|
143
|
-
meta: EventMeta;
|
|
144
|
-
}
|
|
145
|
-
```
|
|
146
|
-
|
|
147
|
-
**`@classytic/primitives/events` is source of truth** — `EventMeta`, `DomainEvent`, `EventHandler`, `EventLogger`, `EventTransport`, `DeadLetteredEvent`, `PublishManyResult`, `createEvent`, `createChildEvent`, `matchEventPattern` all live there. Arc consumes them and re-exports the runtime `MemoryEventTransport`.
|
|
148
|
-
|
|
149
|
-
### DDD aggregate narrowing
|
|
150
|
-
|
|
151
|
-
`aggregate.type` is `string` in arc's base contract so it stays framework-neutral. Domain packages narrow it to a closed union via interface extension:
|
|
152
|
-
|
|
153
|
-
```typescript
|
|
154
|
-
// @classytic/cart
|
|
155
|
-
type CartAggregateType = 'cart' | 'cart-item';
|
|
156
|
-
|
|
157
|
-
interface CartEventMeta extends EventMeta {
|
|
158
|
-
aggregate?: { type: CartAggregateType; id: string };
|
|
159
|
-
}
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
Unlike `correlationId` / `causationId`, `aggregate` is **not inherited** by `createChildEvent`. Child events usually belong to a different aggregate (e.g. an `order.placed` event emitted by the order aggregate spawns `inventory.reserved` owned by the inventory aggregate). Each event names its own aggregate explicitly.
|
|
163
|
-
|
|
164
|
-
### Causation chains
|
|
165
|
-
|
|
166
|
-
```typescript
|
|
167
|
-
import { createEvent, createChildEvent } from '@classytic/primitives/events';
|
|
168
|
-
|
|
169
|
-
const placed = createEvent('order.placed', { orderId: 'o1' }, {
|
|
170
|
-
correlationId: req.id, userId: user.id,
|
|
171
|
-
});
|
|
172
|
-
|
|
173
|
-
// Downstream handler emits child — causation linked, correlation inherited:
|
|
61
|
+
const placed = createEvent('order.placed', { orderId: 'o1' }, { correlationId: req.id });
|
|
174
62
|
const reserved = createChildEvent(placed, 'inventory.reserved', { sku: 'a' });
|
|
175
|
-
// reserved.meta.causationId
|
|
176
|
-
// reserved.meta.correlationId === placed.meta.correlationId
|
|
177
|
-
```
|
|
178
|
-
|
|
179
|
-
### Dead-letter contract
|
|
180
|
-
|
|
181
|
-
```typescript
|
|
182
|
-
import type { DeadLetteredEvent, EventTransport } from '@classytic/primitives/events';
|
|
183
|
-
|
|
184
|
-
class KafkaTransport implements EventTransport {
|
|
185
|
-
async deadLetter(dlq: DeadLetteredEvent) {
|
|
186
|
-
await producer.send({ topic: `${dlq.event.type}.DLQ`, messages: [{ value: JSON.stringify(dlq) }] });
|
|
187
|
-
}
|
|
188
|
-
}
|
|
189
|
-
```
|
|
190
|
-
|
|
191
|
-
## Custom Transport
|
|
192
|
-
|
|
193
|
-
Implement `EventTransport` for RabbitMQ, Kafka, etc.:
|
|
194
|
-
|
|
195
|
-
```typescript
|
|
196
|
-
import type { EventTransport, DomainEvent } from '@classytic/primitives/events';
|
|
197
|
-
|
|
198
|
-
class KafkaTransport implements EventTransport {
|
|
199
|
-
readonly name = 'kafka';
|
|
200
|
-
|
|
201
|
-
async publish(event: DomainEvent): Promise<void> {
|
|
202
|
-
await this.producer.send({ topic: event.type, messages: [{ value: JSON.stringify(event) }] });
|
|
203
|
-
}
|
|
204
|
-
|
|
205
|
-
async subscribe(pattern: string, handler: EventHandler): Promise<() => void> {
|
|
206
|
-
// Subscribe to Kafka topic matching pattern
|
|
207
|
-
return () => { /* unsubscribe */ };
|
|
208
|
-
}
|
|
209
|
-
|
|
210
|
-
async close(): Promise<void> {
|
|
211
|
-
await this.producer.disconnect();
|
|
212
|
-
}
|
|
213
|
-
}
|
|
214
|
-
```
|
|
215
|
-
|
|
216
|
-
## Built-in Transports
|
|
217
|
-
|
|
218
|
-
| Transport | Import | Use Case |
|
|
219
|
-
|-----------|--------|----------|
|
|
220
|
-
| Memory | `@classytic/arc/events` (default) | Development, testing, single-instance |
|
|
221
|
-
| Redis Pub/Sub | `@classytic/arc/events/redis` | Multi-instance, real-time |
|
|
222
|
-
| Redis Streams | `@classytic/arc/events/redis-stream` | Ordered, persistent, consumer groups |
|
|
223
|
-
|
|
224
|
-
### Streams vs Pub/Sub — pick the right one
|
|
225
|
-
|
|
226
|
-
Choosing wrong loses messages silently. Default to **Streams** for anything business-critical.
|
|
227
|
-
|
|
228
|
-
| Requirement | Use |
|
|
229
|
-
|---|---|
|
|
230
|
-
| Message MUST NOT be lost (billing, payments, audit) | **Streams** |
|
|
231
|
-
| Real-time notifications, OK to miss when no subscriber is up | Pub/Sub |
|
|
232
|
-
| Need to replay/reprocess past events | **Streams** |
|
|
233
|
-
| Multiple workers processing the same queue | **Streams** (consumer groups) |
|
|
234
|
-
| Simple broadcast to live WebSocket clients | Pub/Sub |
|
|
235
|
-
| Event sourcing or audit trail | **Streams** |
|
|
236
|
-
| Single-instance dev | Memory |
|
|
237
|
-
| At-least-once delivery with durable WAL | **Streams** + outbox pattern |
|
|
238
|
-
|
|
239
|
-
**Why it matters:** Pub/Sub is fire-and-forget. If no subscriber is connected when you publish, the message is gone. Streams persist until every consumer group acknowledges them — crashes, restarts, and network blips are survivable.
|
|
240
|
-
|
|
241
|
-
**Defense-in-depth:** pair `eventPlugin` with the transactional outbox (`EventOutbox` + `MemoryOutboxStore` or your own persistent store) for guaranteed delivery even if Redis is unreachable at publish time.
|
|
242
|
-
|
|
243
|
-
### Redis eviction policy — required for queues and idempotency
|
|
244
|
-
|
|
245
|
-
When you back events (Streams), jobs (BullMQ), idempotency, or cache with Redis, your Redis instance **must** be configured with `maxmemory-policy: noeviction`. Any other policy can silently evict in-flight stream entries or pending jobs.
|
|
246
|
-
|
|
247
|
-
- **Self-hosted Redis:** `redis-cli CONFIG SET maxmemory-policy noeviction` (or set in `redis.conf`).
|
|
248
|
-
- **Upstash:** free/paid DBs default to `optimistic-volatile`. You'll see `IMPORTANT! Eviction policy is optimistic-volatile. It should be "noeviction"` in BullMQ logs. **Do one of:** open a support ticket to request `noeviction`, use a dedicated DB for queues, or accept that long-idle jobs may be evicted.
|
|
249
|
-
- **ElastiCache / Redis Cloud:** set the parameter group's `maxmemory-policy` to `noeviction` before pointing arc at it.
|
|
250
|
-
|
|
251
|
-
For a pure cache DB (no queues, no idempotency), `allkeys-lru` is correct and what you want.
|
|
252
|
-
|
|
253
|
-
## Injectable Logger
|
|
254
|
-
|
|
255
|
-
All transports and retry accept a `logger` option — defaults to `console`, compatible with pino/fastify.log:
|
|
256
|
-
|
|
257
|
-
```typescript
|
|
258
|
-
import type { EventLogger } from '@classytic/primitives/events';
|
|
259
|
-
|
|
260
|
-
// Interface: { warn(msg, ...args): void; error(msg, ...args): void }
|
|
261
|
-
|
|
262
|
-
// Use Fastify's logger
|
|
263
|
-
await fastify.register(eventPlugin, {
|
|
264
|
-
transport: new RedisEventTransport(redisClient, {
|
|
265
|
-
logger: fastify.log, // pino logger
|
|
266
|
-
}),
|
|
267
|
-
});
|
|
268
|
-
|
|
269
|
-
// Use with Memory transport
|
|
270
|
-
new MemoryEventTransport({ logger: fastify.log });
|
|
271
|
-
|
|
272
|
-
// Use with Redis Streams
|
|
273
|
-
new RedisStreamTransport(redisClient, { logger: fastify.log });
|
|
274
|
-
|
|
275
|
-
// Use with retry wrapper
|
|
276
|
-
import { withRetry } from '@classytic/arc/events';
|
|
277
|
-
const retried = withRetry(handler, { maxRetries: 3, logger: fastify.log });
|
|
63
|
+
// reserved.meta.causationId === placed.meta.id; correlationId inherited; aggregate is NOT inherited
|
|
278
64
|
```
|
|
279
65
|
|
|
280
|
-
|
|
281
|
-
|-----------|------|-----------------|
|
|
282
|
-
| `MemoryEventTransport` | `EventTransport.ts` | `MemoryEventTransportOptions.logger` |
|
|
283
|
-
| `withRetry()` | `retry.ts` | `RetryOptions.logger` |
|
|
284
|
-
| `RedisEventTransport` | `transports/redis.ts` | `RedisEventTransportOptions.logger` |
|
|
285
|
-
| `RedisStreamTransport` | `transports/redis-stream.ts` | `RedisStreamTransportOptions.logger` |
|
|
286
|
-
|
|
287
|
-
## Typed Events — defineEvent & Event Registry
|
|
288
|
-
|
|
289
|
-
Declare events with schemas for runtime validation and introspection:
|
|
66
|
+
## Typed events and registry
|
|
290
67
|
|
|
291
68
|
```typescript
|
|
69
|
+
import { z } from 'zod';
|
|
292
70
|
import { defineEvent, createEventRegistry } from '@classytic/arc/events';
|
|
293
71
|
|
|
294
|
-
const
|
|
295
|
-
name: 'order.
|
|
296
|
-
|
|
297
|
-
description: 'Emitted when an order is placed',
|
|
298
|
-
schema: {
|
|
299
|
-
type: 'object',
|
|
300
|
-
properties: {
|
|
301
|
-
orderId: { type: 'string' },
|
|
302
|
-
total: { type: 'number' },
|
|
303
|
-
},
|
|
304
|
-
required: ['orderId', 'total'],
|
|
305
|
-
},
|
|
72
|
+
const OrderPlaced = defineEvent({
|
|
73
|
+
name: 'order.placed', version: 1,
|
|
74
|
+
payload: z.object({ orderId: z.string(), total: z.number() }), // zod v4; or raw `schema` (JSON Schema)
|
|
306
75
|
});
|
|
307
|
-
|
|
308
|
-
// Type-safe event creation
|
|
309
|
-
const event = OrderCreated.create({ orderId: 'o-1', total: 100 }, { userId: 'user-1' });
|
|
76
|
+
const event = OrderPlaced.create({ orderId: 'o1', total: 10 }, { userId: 'u1' });
|
|
310
77
|
await app.events.publish(event.type, event.payload, event.meta);
|
|
311
|
-
```
|
|
312
78
|
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
const registry = createEventRegistry();
|
|
317
|
-
registry.register(OrderCreated);
|
|
318
|
-
|
|
319
|
-
const app = await createApp({
|
|
320
|
-
arcPlugins: {
|
|
321
|
-
events: { registry, validateMode: 'warn' },
|
|
322
|
-
// 'warn' (default): log warning, still publish
|
|
323
|
-
// 'reject': throw error, do NOT publish
|
|
324
|
-
// 'off': registry is introspection-only
|
|
325
|
-
},
|
|
326
|
-
});
|
|
327
|
-
|
|
328
|
-
// Introspect at runtime
|
|
329
|
-
app.events.registry?.catalog();
|
|
330
|
-
// → [{ name: 'order.created', version: 1, schema: {...} }, ...]
|
|
79
|
+
const registry = createEventRegistry(); // optional { validate } to plug a full validator
|
|
80
|
+
registry.register(OrderPlaced);
|
|
81
|
+
createApp({ arcPlugins: { events: { registry, validateMode: 'reject' } } });
|
|
331
82
|
```
|
|
332
83
|
|
|
333
|
-
|
|
84
|
+
- Declare `payload` or `schema`, never both.
|
|
85
|
+
- Money or stock events: `durability: 'durable'` plus `occurrence(payload)` (fixed id). `app.events.publish` refuses them with `NonDurablePublishError`; write them to the outbox (see events-outbox.md).
|
|
334
86
|
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
## Retry Logic
|
|
338
|
-
|
|
339
|
-
Events module includes retry with exponential backoff for failed handlers:
|
|
87
|
+
## Handler wrappers
|
|
340
88
|
|
|
341
89
|
```typescript
|
|
342
|
-
import { withRetry
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
});
|
|
352
|
-
|
|
353
|
-
await
|
|
90
|
+
import { withRetry, wrapWithSchema, subscribeWithSchema, wrapWithBoundary, subscribeWithBoundary,
|
|
91
|
+
withSubscriberId, withInbox, createDeadLetterPublisher } from '@classytic/arc/events';
|
|
92
|
+
|
|
93
|
+
await app.events.subscribe('order.placed', withRetry(handler, {
|
|
94
|
+
maxRetries: 3, backoffMs: 1000, maxBackoffMs: 30000, jitter: 0.1,
|
|
95
|
+
transport, // your EventTransport: exhausted events go to transport.deadLetter()
|
|
96
|
+
name: 'emailer', // DeadLetteredEvent.handlerName
|
|
97
|
+
onDead: (event, errors) => alert(event), // observability only, errors swallowed
|
|
98
|
+
dlqFailureMode: 'rethrow', // default; 'log-and-drop' acknowledges losses
|
|
99
|
+
}));
|
|
100
|
+
await subscribeWithSchema(app, OrderPlaced, handler); // typed payload, invalid events skipped
|
|
101
|
+
await subscribeWithBoundary(app, 'cache.*', invalidate); // log and swallow, no retry
|
|
354
102
|
```
|
|
355
103
|
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
`
|
|
360
|
-
|
|
361
|
-
```typescript
|
|
362
|
-
await fastify.events.subscribe(
|
|
363
|
-
'order.created',
|
|
364
|
-
withRetry(handler, {
|
|
365
|
-
maxRetries: 3,
|
|
366
|
-
transport: fastify.events.transport, // any EventTransport with deadLetter()
|
|
367
|
-
name: 'emailProcessor', // populates DeadLetteredEvent.handlerName
|
|
368
|
-
}),
|
|
369
|
-
);
|
|
370
|
-
```
|
|
371
|
-
|
|
372
|
-
On exhaustion, a typed `DeadLetteredEvent` envelope (original event + error +
|
|
373
|
-
attempts + first/last failure timestamps) is handed to `transport.deadLetter()`.
|
|
374
|
-
`onDead` still works — both fire when both are configured.
|
|
375
|
-
|
|
376
|
-
## Transactional Outbox (v2.9)
|
|
377
|
-
|
|
378
|
-
**Why the outbox exists:** you write a row + publish an event in the same user
|
|
379
|
-
request. If the transport (Redis/Kafka) is down at that moment, the row
|
|
380
|
-
commits but the event vanishes — silent data divergence. The outbox persists
|
|
381
|
-
the event in the **same DB transaction** as the row, then a background relayer
|
|
382
|
-
guarantees at-least-once delivery to the transport. Multi-worker claim +
|
|
383
|
-
retry/DLQ policy + dedupe make it scale.
|
|
384
|
-
|
|
385
|
-
`EventOutbox` now offers centralised retry/DLQ and typed DLQ query:
|
|
386
|
-
|
|
387
|
-
```typescript
|
|
388
|
-
import { EventOutbox, MemoryOutboxStore, exponentialBackoff } from '@classytic/arc/events';
|
|
389
|
-
|
|
390
|
-
const outbox = new EventOutbox({
|
|
391
|
-
store: new MemoryOutboxStore(), // swap for durable store in prod
|
|
392
|
-
transport: fastify.events.transport,
|
|
393
|
-
|
|
394
|
-
// Centralised retry/DLQ — no more hand-rolled exponentialBackoff at every fail site
|
|
395
|
-
failurePolicy: ({ attempts, error }) => {
|
|
396
|
-
if (attempts >= 5) return { deadLetter: true };
|
|
397
|
-
return { retryAt: exponentialBackoff({ attempt: attempts }) };
|
|
398
|
-
},
|
|
399
|
-
});
|
|
400
|
-
|
|
401
|
-
// meta.idempotencyKey auto-maps to OutboxWriteOptions.dedupeKey — duplicate
|
|
402
|
-
// saves with the same key are silently absorbed.
|
|
403
|
-
await outbox.store(
|
|
404
|
-
createEvent('order.placed', payload, { idempotencyKey: `order:${id}:placed` }),
|
|
405
|
-
);
|
|
406
|
-
|
|
407
|
-
// Rich per-batch outcome — deadLettered is new in v2.9
|
|
408
|
-
const result = await outbox.relayBatch();
|
|
409
|
-
// { relayed, attempted, publishFailed, ackFailed, ownershipMismatches,
|
|
410
|
-
// malformed, failHookErrors, deadLettered, usedPublishMany }
|
|
104
|
+
| Helper | Use |
|
|
105
|
+
|---|---|
|
|
106
|
+
| `withSubscriberId(id, handler)` | Stable per-handler identity for durable per-handler progress (never an index) |
|
|
107
|
+
| `withInbox(name, handler, { store, leaseMs?, transaction? })` | Run a handler once per event id; `store` is a repo-core `IdempotencyClaimStore`; handler gets `{ session, eventId }` |
|
|
108
|
+
| `createDeadLetterPublisher(app.events)` | Handler that publishes exhausted events to `$deadLetter`; pass as `onDead` or `deadLetter` |
|
|
411
109
|
|
|
412
|
-
|
|
413
|
-
const dlq = await outbox.getDeadLettered(100);
|
|
414
|
-
for (const envelope of dlq) {
|
|
415
|
-
await alertOps(envelope); // event, error, attempts, firstFailedAt, lastFailedAt
|
|
416
|
-
}
|
|
417
|
-
```
|
|
110
|
+
Dead-letter contract: a transport may implement `deadLetter(dlq: DeadLetteredEvent)`.
|
|
418
111
|
|
|
419
|
-
|
|
112
|
+
## Transports
|
|
420
113
|
|
|
421
|
-
|
|
|
114
|
+
| Transport | Import | Use |
|
|
422
115
|
|---|---|---|
|
|
423
|
-
| `
|
|
424
|
-
| `
|
|
425
|
-
| `
|
|
426
|
-
| `getDeadLettered` | — | `outbox.getDeadLettered()` returns `[]` |
|
|
427
|
-
| `purge` | — | App owns retention (TTL index, cron DELETE, etc.) |
|
|
428
|
-
|
|
429
|
-
`MemoryOutboxStore` implements all capabilities — use it as a reference when
|
|
430
|
-
writing a durable store for Postgres / DynamoDB / your DB of choice.
|
|
431
|
-
|
|
432
|
-
### Durable store — pass a `RepositoryLike`
|
|
433
|
-
|
|
434
|
-
Arc adapts any `Repository` (mongokit / prismakit / your own kit) to the
|
|
435
|
-
`OutboxStore` contract — no dedicated subpath, no store class to
|
|
436
|
-
instantiate:
|
|
437
|
-
|
|
438
|
-
```typescript
|
|
439
|
-
import mongoose from 'mongoose';
|
|
440
|
-
import { Repository } from '@classytic/mongokit';
|
|
441
|
-
import { EventOutbox, exponentialBackoff, createEvent } from '@classytic/arc/events';
|
|
442
|
-
|
|
443
|
-
const OutboxModel = mongoose.model('ArcOutbox', OutboxSchema, 'arc_outbox_events');
|
|
444
|
-
|
|
445
|
-
const outbox = new EventOutbox({
|
|
446
|
-
repository: new Repository(OutboxModel),
|
|
447
|
-
transport: redisTransport,
|
|
448
|
-
failurePolicy: ({ attempts }) =>
|
|
449
|
-
attempts >= 5 ? { deadLetter: true } : { retryAt: exponentialBackoff({ attempt: attempts }) },
|
|
450
|
-
});
|
|
451
|
-
|
|
452
|
-
// Persist event in the same DB transaction as the row
|
|
453
|
-
await mongoose.connection.transaction(async (session) => {
|
|
454
|
-
await Order.create([orderDoc], { session });
|
|
455
|
-
await outbox.store(
|
|
456
|
-
createEvent('order.placed', { orderId }, { idempotencyKey: `order:${orderId}:placed` }),
|
|
457
|
-
{ session },
|
|
458
|
-
);
|
|
459
|
-
});
|
|
460
|
-
|
|
461
|
-
// Background relayer
|
|
462
|
-
setInterval(async () => {
|
|
463
|
-
const r = await outbox.relayBatch();
|
|
464
|
-
metrics.gauge('outbox.deadLettered', r.deadLettered);
|
|
465
|
-
}, 1000);
|
|
466
|
-
|
|
467
|
-
// Ops: read dead-letter envelopes for alerting / replay
|
|
468
|
-
const dlq = await outbox.getDeadLettered(100);
|
|
469
|
-
```
|
|
470
|
-
|
|
471
|
-
**What you get:**
|
|
116
|
+
| `MemoryEventTransport` | `@classytic/arc/events` | Dev, tests, one process |
|
|
117
|
+
| `RedisEventTransport(redis, { channel, externalLifecycle, logger })` | `@classytic/arc/events/redis` | Pub/Sub, fire-and-forget, live fan-out |
|
|
118
|
+
| `RedisStreamTransport(redis, opts)` | `@classytic/arc/events/redis-stream` | Persistent, consumer groups, replay, DLQ stream |
|
|
472
119
|
|
|
473
|
-
|
|
474
|
-
on `{ status: 'pending', visibleAt ≤ now, lease free }`. Two racing
|
|
475
|
-
relayers never see the same event; expired leases auto-recover.
|
|
476
|
-
- **Session threading** — `outbox.store(event, { session })` flows
|
|
477
|
-
through `Repository.create(doc, { session })` so the event commits
|
|
478
|
-
with your business write.
|
|
479
|
-
- **Dedupe** — `meta.idempotencyKey` maps to `dedupeKey`; your kit's
|
|
480
|
-
unique index (or equivalent) enforces idempotency.
|
|
481
|
-
- **DLQ** — `getDeadLettered(limit)` returns typed `DeadLetteredEvent[]`.
|
|
482
|
-
`RelayResult.deadLettered` counts per-batch transitions.
|
|
483
|
-
- **Purge** — `outbox.purge(olderThanMs)` deletes delivered rows; define
|
|
484
|
-
retention via a TTL index (`deliveredAt`), a cron, or a scheduler —
|
|
485
|
-
your kit's choice.
|
|
120
|
+
Streams options: `stream` ('arc:events'), `group` ('default'), `consumer`, `blockTimeMs` (5000), `batchSize` (10), `processingConcurrency` (1, keeps order), `maxRetries` (5), `claimTimeoutMs` (30000), `deadLetterStream` ('arc:events:dlq' or `false`), `maxLen` (0), `groupStart` ('latest' | 'beginning'), `maxPayloadBytes` (1 MB), `externalLifecycle`.
|
|
486
121
|
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
122
|
+
- Pub/Sub loses events when no subscriber is connected. Use Streams for billing, payments, audit, replay.
|
|
123
|
+
- Redis backing events, BullMQ jobs, or idempotency needs `maxmemory-policy noeviction`. Pure caches use `allkeys-lru`.
|
|
124
|
+
- Custom transport: implement `EventTransport` (`name`, `publish`, `subscribe(pattern, handler)` returning unsubscribe, `close`, optional `deadLetter`, `publishMany`).
|
|
125
|
+
- Every transport and wrapper takes `logger` (`fastify.log` works).
|
|
126
|
+
- Multi-instance deployments must not rely on the default memory transport.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# Jobs (BullMQ)
|
|
2
|
+
|
|
3
|
+
```typescript
|
|
4
|
+
import { jobsPlugin, defineJob } from '@classytic/arc/integrations/jobs';
|
|
5
|
+
```
|
|
6
|
+
|
|
7
|
+
Peers: `bullmq`, Redis (with `maxmemory-policy noeviction`).
|
|
8
|
+
|
|
9
|
+
## Define
|
|
10
|
+
|
|
11
|
+
```typescript
|
|
12
|
+
const sendEmail = defineJob({
|
|
13
|
+
name: 'send-email', // unique; also the queue name
|
|
14
|
+
handler: async (data: { to: string; subject: string }, meta) => {
|
|
15
|
+
await mailer.send(data.to, data.subject, { signal: meta.signal });
|
|
16
|
+
return { sent: true };
|
|
17
|
+
},
|
|
18
|
+
retries: 3, // default 3
|
|
19
|
+
backoff: { type: 'exponential', delay: 1000 },
|
|
20
|
+
timeout: 30000, // default 30000; aborts meta.signal
|
|
21
|
+
concurrency: 5, // BullMQ concurrency per worker
|
|
22
|
+
maxConcurrent: 2, // arc semaphore for a downstream limit
|
|
23
|
+
cancelGraceMs: 30000, // max time a timed-out handler holds its slot
|
|
24
|
+
rateLimit: { max: 100, duration: 60000 },
|
|
25
|
+
deadLetterQueue: 'send-email:dead', // default '<name>-dead'
|
|
26
|
+
repeat: { pattern: '0 9 * * *', tz: 'UTC' }, // cron needs tz; or { every: ms }, plus endDate, limit
|
|
27
|
+
});
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
- `meta`: `{ jobId, attemptsMade, timestamp, signal }`. Pass `signal` to fetch and DB calls, or a timed-out handler keeps running and a retry can overlap it. Make handlers idempotent.
|
|
31
|
+
|
|
32
|
+
## Register
|
|
33
|
+
|
|
34
|
+
```typescript
|
|
35
|
+
await app.register(jobsPlugin, {
|
|
36
|
+
connection: { host: 'localhost', port: 6379 },
|
|
37
|
+
jobs: [sendEmail],
|
|
38
|
+
mode: 'both', // 'producer' (queues only, API fleets) | 'worker' | 'both'
|
|
39
|
+
bridgeEvents: true, // default
|
|
40
|
+
defaults: { retries: 3, backoff: { type: 'exponential', delay: 1000 }, removeOnComplete: 100, removeOnFail: 500 },
|
|
41
|
+
});
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Repeat schedules are reconciled by the side that runs workers.
|
|
45
|
+
|
|
46
|
+
## Dispatch
|
|
47
|
+
|
|
48
|
+
```typescript
|
|
49
|
+
const { queue, jobId } = await app.jobs.dispatch('send-email', { to: 'a@b.co', subject: 'Hi' }, {
|
|
50
|
+
delay: 5000, priority: 1, jobId: 'dedupe-key', removeOnComplete: true,
|
|
51
|
+
});
|
|
52
|
+
const status = await app.jobs.getStatus(queue, jobId); // JobStatus | null; ids are queue-local
|
|
53
|
+
const stats = await app.jobs.getStats(); // { [queue]: { waiting, active, completed, failed, delayed } }
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
`app.jobs` also has `getQueue(name)` and `close()`.
|
|
57
|
+
|
|
58
|
+
## Management routes (off by default)
|
|
59
|
+
|
|
60
|
+
```typescript
|
|
61
|
+
import { requirePlatformRole } from '@classytic/arc/permissions';
|
|
62
|
+
|
|
63
|
+
managementRoutes: {
|
|
64
|
+
operatorPermission: requirePlatformRole('platform-ops'), // required, platform-only
|
|
65
|
+
exposeResult: false, // default: hide returnValue
|
|
66
|
+
exposeFailureReason: false, // default: hide failedReason
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Mounts `GET <prefix>/stats` (prefix default `/jobs`) and `GET <prefix>/:queue/:id/status`. Both are global (a job carries no tenant), so org-role gates are refused at boot; `allowUnverifiedOperatorPermission: true` accepts a custom check you verified.
|
|
71
|
+
|
|
72
|
+
## Event bridge
|
|
73
|
+
|
|
74
|
+
With `bridgeEvents`, the bus gets `job.<name>.completed` (`{ jobId, data, result }`), `job.<name>.failed` (`{ jobId, data, error, attemptsMade }`), `job.<name>.stalled` (`{ jobId }`). Publishing is best effort and never fails the worker.
|