@cat-factory/caching 0.4.22 → 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 +2 -0
- package/dist/appCaches.d.ts.map +1 -1
- package/dist/appCaches.js +35 -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,8 @@ export interface AppCachesProfile {
|
|
|
34
34
|
fragmentCatalog: GroupCacheProfile;
|
|
35
35
|
fragmentDocumentBody: GroupCacheProfile;
|
|
36
36
|
repoProjection: GroupCacheProfile;
|
|
37
|
+
repoFiles: GroupCacheProfile;
|
|
38
|
+
accountModelPolicy: GroupCacheProfile;
|
|
37
39
|
}
|
|
38
40
|
/** The default (Node/local/test) profile: caching on, modest bounds. */
|
|
39
41
|
export declare const DEFAULT_APP_CACHES_PROFILE: AppCachesProfile;
|
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,
|
|
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,26 @@ 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
|
+
},
|
|
38
|
+
// One resolved model-family policy per account, keyed by account id (one entry per
|
|
39
|
+
// group). Slow-moving (admin-changed); invalidation-driven, no version probe.
|
|
40
|
+
accountModelPolicy: {
|
|
41
|
+
enabled: true,
|
|
42
|
+
ttlInMsecs: 5 * 60_000,
|
|
43
|
+
maxGroups: 2000,
|
|
44
|
+
maxItemsPerGroup: 1,
|
|
45
|
+
},
|
|
26
46
|
};
|
|
27
47
|
/**
|
|
28
48
|
* The Cloudflare Worker profile: every cache of mutable cross-instance state is
|
|
@@ -45,6 +65,15 @@ export const ISOLATE_SAFE_APP_CACHES_PROFILE = {
|
|
|
45
65
|
// whose external entries self-verify via a version probe). So the Worker reads it
|
|
46
66
|
// live every time, exactly like `fragmentCatalog`.
|
|
47
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 },
|
|
74
|
+
// Pass-through for the same reason: the account policy is our own mutable D1 state
|
|
75
|
+
// with no cross-isolate invalidation bus on the Worker.
|
|
76
|
+
accountModelPolicy: { ...DEFAULT_APP_CACHES_PROFILE.accountModelPolicy, enabled: false },
|
|
48
77
|
};
|
|
49
78
|
class LayeredGroupCacheHandle {
|
|
50
79
|
loader;
|
|
@@ -127,15 +156,21 @@ export function createAppCaches(options = {}) {
|
|
|
127
156
|
const fragmentCatalog = buildGroupCache('fragment-catalog', profile.fragmentCatalog, options);
|
|
128
157
|
const fragmentDocumentBody = buildGroupCache('fragment-document-body', profile.fragmentDocumentBody, options);
|
|
129
158
|
const repoProjection = buildGroupCache('repo-projection', profile.repoProjection, options);
|
|
159
|
+
const repoFiles = buildGroupCache('repo-files', profile.repoFiles, options);
|
|
160
|
+
const accountModelPolicy = buildGroupCache('account-model-policy', profile.accountModelPolicy, options);
|
|
130
161
|
return {
|
|
131
162
|
fragmentCatalog,
|
|
132
163
|
fragmentDocumentBody,
|
|
133
164
|
repoProjection,
|
|
165
|
+
repoFiles,
|
|
166
|
+
accountModelPolicy,
|
|
134
167
|
close: async () => {
|
|
135
168
|
await Promise.all([
|
|
136
169
|
fragmentCatalog.close(),
|
|
137
170
|
fragmentDocumentBody.close(),
|
|
138
171
|
repoProjection.close(),
|
|
172
|
+
repoFiles.close(),
|
|
173
|
+
accountModelPolicy.close(),
|
|
139
174
|
]);
|
|
140
175
|
},
|
|
141
176
|
};
|
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",
|