@cat-factory/caching 0.5.0 → 0.6.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 +6 -4
- package/dist/appCaches.d.ts +1 -0
- package/dist/appCaches.d.ts.map +1 -1
- package/dist/appCaches.js +21 -0
- package/dist/appCaches.js.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -53,10 +53,12 @@ read. Only `fragmentCatalog`, which mirrors our own mutable D1 rows, passes thro
|
|
|
53
53
|
|
|
54
54
|
## Named caches
|
|
55
55
|
|
|
56
|
-
| Cache | Value | Group / key
|
|
57
|
-
| ---------------------- | ----------------------------------------------- |
|
|
58
|
-
| `fragmentCatalog` | merged per-workspace catalog | `workspaceId` / `workspaceId`
|
|
59
|
-
| `fragmentDocumentBody` | a document-backed fragment's live external body | `viaWorkspaceId` / `<source>:<externalId>`
|
|
56
|
+
| Cache | Value | Group / key | Profile |
|
|
57
|
+
| ---------------------- | ----------------------------------------------- | ---------------------------------------------------- | --------------------------------------------- |
|
|
58
|
+
| `fragmentCatalog` | merged per-workspace catalog | `workspaceId` / `workspaceId` | TTL + invalidation; pass-through on Worker |
|
|
59
|
+
| `fragmentDocumentBody` | a document-backed fragment's live external body | `viaWorkspaceId` / `<source>:<externalId>` | TTL + version probe; enabled on both facades |
|
|
60
|
+
| `repoProjection` | a workspace's whole GitHub repo projection | `workspaceId` / `workspaceId` | TTL + invalidation; pass-through on Worker |
|
|
61
|
+
| `repoFiles` | checkout-free `RepoFiles` reads on a branch | `<inst>:<owner>/<repo>@<branch>` / `f:`\|`d:` + path | TTL + head-sha probe; enabled on both facades |
|
|
60
62
|
|
|
61
63
|
## Usage
|
|
62
64
|
|
package/dist/appCaches.d.ts
CHANGED
|
@@ -34,6 +34,7 @@ export interface AppCachesProfile {
|
|
|
34
34
|
fragmentCatalog: GroupCacheProfile;
|
|
35
35
|
fragmentDocumentBody: GroupCacheProfile;
|
|
36
36
|
repoProjection: GroupCacheProfile;
|
|
37
|
+
repoFiles: GroupCacheProfile;
|
|
37
38
|
accountModelPolicy: GroupCacheProfile;
|
|
38
39
|
}
|
|
39
40
|
/** The default (Node/local/test) profile: caching on, modest bounds. */
|
package/dist/appCaches.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"appCaches.d.ts","sourceRoot":"","sources":["../src/appCaches.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,SAAS,
|
|
1
|
+
{"version":3,"file":"appCaches.d.ts","sourceRoot":"","sources":["../src/appCaches.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,SAAS,EAMV,MAAM,qBAAqB,CAAA;AAM5B,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,uEAAuE,CAAA;AACzH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qEAAqE,CAAA;AACrH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sDAAsD,CAAA;AAC9F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wCAAwC,CAAA;AAUpE,wFAAwF;AACxF,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,OAAO,EAAE,OAAO,CAAA;IAChB,mFAAmF;IACnF,UAAU,EAAE,MAAM,CAAA;IAClB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAA;IACjB,6CAA6C;IAC7C,gBAAgB,EAAE,MAAM,CAAA;IACxB;;;;;;;;OAQG;IACH,2BAA2B,CAAC,EAAE,MAAM,CAAA;CACrC;AAED,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAC/B,eAAe,EAAE,iBAAiB,CAAA;IAClC,oBAAoB,EAAE,iBAAiB,CAAA;IACvC,cAAc,EAAE,iBAAiB,CAAA;IACjC,SAAS,EAAE,iBAAiB,CAAA;IAC5B,kBAAkB,EAAE,iBAAiB,CAAA;CACtC;AAED,wEAAwE;AACxE,eAAO,MAAM,0BAA0B,EAAE,gBAuCxC,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,+BAA+B,EAAE,gBAiB7C,CAAA;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACxC,SAAS,EAAE,0BAA0B,CAAC,CAAC,CAAC,CAAA;IACxC,QAAQ,EAAE,4BAA4B,CAAC,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAA;CACjE;AAED;;;;;GAKG;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,EAC3C,SAAS,EAAE,MAAM,KACd,uBAAuB,CAAC,CAAC,CAAC,GAAG,SAAS,CAAA;AAE3C,MAAM,WAAW,sBAAsB;IACrC,0EAA0E;IAC1E,OAAO,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAA;IACnC,2EAA2E;IAC3E,uBAAuB,CAAC,EAAE,4BAA4B,CAAA;IACtD,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAqGD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,SAAS,CAuC/E"}
|
package/dist/appCaches.js
CHANGED
|
@@ -23,6 +23,18 @@ export const DEFAULT_APP_CACHES_PROFILE = {
|
|
|
23
23
|
// entry per group). Invalidation-driven — no version probe (a DB read as the probe
|
|
24
24
|
// would cost as much as the DB read as the load).
|
|
25
25
|
repoProjection: { enabled: true, ttlInMsecs: 5 * 60_000, maxGroups: 1000, maxItemsPerGroup: 1 },
|
|
26
|
+
// Checkout-free RepoFiles reads, grouped per (installation, repo, branch) and keyed per
|
|
27
|
+
// path. Self-verifying like the document body: an entry entering the last minute of its
|
|
28
|
+
// TTL runs the branch's cheap `headSha` probe (bump on an unmoved branch, background
|
|
29
|
+
// reload otherwise) so a repo-op re-run doesn't re-fetch every file. A branch can hold
|
|
30
|
+
// many spec/blueprint shards, so a generous per-group bound.
|
|
31
|
+
repoFiles: {
|
|
32
|
+
enabled: true,
|
|
33
|
+
ttlInMsecs: 5 * 60_000,
|
|
34
|
+
maxGroups: 500,
|
|
35
|
+
maxItemsPerGroup: 256,
|
|
36
|
+
ttlLeftBeforeRefreshInMsecs: 60_000,
|
|
37
|
+
},
|
|
26
38
|
// One resolved model-family policy per account, keyed by account id (one entry per
|
|
27
39
|
// group). Slow-moving (admin-changed); invalidation-driven, no version probe.
|
|
28
40
|
accountModelPolicy: {
|
|
@@ -53,6 +65,12 @@ export const ISOLATE_SAFE_APP_CACHES_PROFILE = {
|
|
|
53
65
|
// whose external entries self-verify via a version probe). So the Worker reads it
|
|
54
66
|
// live every time, exactly like `fragmentCatalog`.
|
|
55
67
|
repoProjection: { ...DEFAULT_APP_CACHES_PROFILE.repoProjection, enabled: false },
|
|
68
|
+
// Stays ENABLED here: a RepoFiles branch read is re-validated by the branch `headSha`
|
|
69
|
+
// probe (the git analogue of the document-body version probe), so a peer isolate's cached
|
|
70
|
+
// file self-heals within the refresh window without an invalidation bus — its staleness is
|
|
71
|
+
// bounded by the probe, not indefinite. The same reasoning that keeps `fragmentDocumentBody`
|
|
72
|
+
// on; only caches of our own mutable D1 state (`fragmentCatalog`/`repoProjection`) pass through.
|
|
73
|
+
repoFiles: { ...DEFAULT_APP_CACHES_PROFILE.repoFiles },
|
|
56
74
|
// Pass-through for the same reason: the account policy is our own mutable D1 state
|
|
57
75
|
// with no cross-isolate invalidation bus on the Worker.
|
|
58
76
|
accountModelPolicy: { ...DEFAULT_APP_CACHES_PROFILE.accountModelPolicy, enabled: false },
|
|
@@ -138,17 +156,20 @@ export function createAppCaches(options = {}) {
|
|
|
138
156
|
const fragmentCatalog = buildGroupCache('fragment-catalog', profile.fragmentCatalog, options);
|
|
139
157
|
const fragmentDocumentBody = buildGroupCache('fragment-document-body', profile.fragmentDocumentBody, options);
|
|
140
158
|
const repoProjection = buildGroupCache('repo-projection', profile.repoProjection, options);
|
|
159
|
+
const repoFiles = buildGroupCache('repo-files', profile.repoFiles, options);
|
|
141
160
|
const accountModelPolicy = buildGroupCache('account-model-policy', profile.accountModelPolicy, options);
|
|
142
161
|
return {
|
|
143
162
|
fragmentCatalog,
|
|
144
163
|
fragmentDocumentBody,
|
|
145
164
|
repoProjection,
|
|
165
|
+
repoFiles,
|
|
146
166
|
accountModelPolicy,
|
|
147
167
|
close: async () => {
|
|
148
168
|
await Promise.all([
|
|
149
169
|
fragmentCatalog.close(),
|
|
150
170
|
fragmentDocumentBody.close(),
|
|
151
171
|
repoProjection.close(),
|
|
172
|
+
repoFiles.close(),
|
|
152
173
|
accountModelPolicy.close(),
|
|
153
174
|
]);
|
|
154
175
|
},
|
package/dist/appCaches.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"appCaches.js","sourceRoot":"","sources":["../src/appCaches.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"appCaches.js","sourceRoot":"","sources":["../src/appCaches.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cat-factory/caching",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.6.0",
|
|
4
4
|
"description": "The app-level caching seam for the Agent Architecture Board (docs/initiatives/caching-layer.md): createAppCaches builds the named, typed in-memory read-through caches (layered-loader) the services consume via the kernel AppCaches port, with optional distributed invalidation over an injected Redis notification pair. Redis is only ever an invalidation bus, never a data tier.",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -25,7 +25,7 @@
|
|
|
25
25
|
},
|
|
26
26
|
"dependencies": {
|
|
27
27
|
"layered-loader": "^14.5.3",
|
|
28
|
-
"@cat-factory/kernel": "0.
|
|
28
|
+
"@cat-factory/kernel": "0.104.0"
|
|
29
29
|
},
|
|
30
30
|
"devDependencies": {
|
|
31
31
|
"@types/node": "^26.1.0",
|