@drawbridge/drawbridge-agents 0.0.8 → 0.0.9
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/claude/CLAUDE.md +1 -0
- package/conventions/cascade-cleanup.md +25 -0
- package/package.json +1 -1
package/claude/CLAUDE.md
CHANGED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Cascade cleanup belongs in drawbridge-sync
|
|
2
|
+
|
|
3
|
+
When a Drawbridge document delete should trigger cleanup of dependent rows in another collection — actions tied to a workflow, workflows tied to a connection, exports tied to a user, anything where deleting X requires also deleting Y — the cleanup belongs in a change-stream listener in `drawbridge-sync`, **not** inline in the API route handler that triggered the original delete.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
- API routes stay focused on the user's request. Cascade work shouldn't block the HTTP response or balloon the request's transaction scope.
|
|
8
|
+
- A sync-side listener fires on **every** delete path: the direct route, a cascade from a different route, an admin tool, a manual Mongo write. An inline cascade only runs on the one route that has it.
|
|
9
|
+
- Change streams are configured with `fullDocumentBeforeChange: 'required'`, so the listener receives the full prior document and has everything it needs to reason about the dependents.
|
|
10
|
+
|
|
11
|
+
## How to apply
|
|
12
|
+
|
|
13
|
+
- In an API route delete handler, do **not** add `controllers.base.delete` (or `bulk` with `deleteMany`) for child collections. Just delete the parent. The sync listener cleans up.
|
|
14
|
+
- Add the cleanup handler in `drawbridge-sync/queue/<collection>.js`, in the `handlers.delete` slot, signature `async ({ fullDocumentBeforeChange : doc }) => { ... }`. Copy the shape from `queue/user.js` or `queue/organization.js`.
|
|
15
|
+
- For the listener to fire at all, the collection must be in both:
|
|
16
|
+
- `drawbridge-sync/stream.js` `collections` array
|
|
17
|
+
- `drawbridge-sync/lib/queue.js` queue map
|
|
18
|
+
- **And** registered in `drawbridge-sync/queue/index.js`'s workers array.
|
|
19
|
+
- If any of these are missing, change-stream events get enqueued and silently dropped, or never enqueued at all. Audit all four sites when adding a new collection.
|
|
20
|
+
- For deep cascades (parent → child → grandchild), let the chain ride the change streams: the child's own listener handles its own dependents. Don't reach down two levels from the parent's listener.
|
|
21
|
+
|
|
22
|
+
## Counter-examples (these stay inline in the API)
|
|
23
|
+
|
|
24
|
+
- Decrementing `organization.totals.<resource>` and `usage.totals.<resource>` on delete. These are counter mutations against the *same* request, not cleanup of dependent rows. Done inline in the API route handler.
|
|
25
|
+
- The deleted document itself. The route deletes it; the listener reacts to the deletion.
|
package/package.json
CHANGED