dsh-token-usage-ledger 0.0.0-stage → 0.0.36
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/CHANGELOG.md +1067 -0
- package/LICENSE +21 -0
- package/README.md +237 -2
- package/cordis.patch.yml +30 -0
- package/lib/client.js +4469 -0
- package/lib/host/aggregate.d.ts +132 -0
- package/lib/host/aggregate.js +840 -0
- package/lib/host/api.d.ts +118 -0
- package/lib/host/api.js +346 -0
- package/lib/host/backfill.d.ts +54 -0
- package/lib/host/backfill.js +265 -0
- package/lib/host/collector.d.ts +139 -0
- package/lib/host/collector.js +441 -0
- package/lib/host/ledger-io.d.ts +125 -0
- package/lib/host/ledger-io.js +211 -0
- package/lib/host/operation-error.d.ts +22 -0
- package/lib/host/operation-error.js +28 -0
- package/lib/host/paths.d.ts +35 -0
- package/lib/host/paths.js +63 -0
- package/lib/host/pricing-module.d.ts +112 -0
- package/lib/host/pricing-module.js +63 -0
- package/lib/host/pricing-modules/deepseek-2026-09-10.d.ts +31 -0
- package/lib/host/pricing-modules/deepseek-2026-09-10.js +67 -0
- package/lib/host/pricing-modules/index.d.ts +27 -0
- package/lib/host/pricing-modules/index.js +30 -0
- package/lib/host/pricing.d.ts +192 -0
- package/lib/host/pricing.js +287 -0
- package/lib/host/records.d.ts +47 -0
- package/lib/host/records.js +116 -0
- package/lib/host/runtime-marker.d.ts +67 -0
- package/lib/host/runtime-marker.js +71 -0
- package/lib/host/schema.d.ts +77 -0
- package/lib/host/schema.js +158 -0
- package/lib/host/store.d.ts +171 -0
- package/lib/host/store.js +337 -0
- package/lib/host/workspace-titles.d.ts +38 -0
- package/lib/host/workspace-titles.js +136 -0
- package/lib/host/zstd.d.ts +41 -0
- package/lib/host/zstd.js +134 -0
- package/lib/index.d.ts +82 -0
- package/lib/index.js +512 -0
- package/lib/shared/format.d.ts +415 -0
- package/lib/shared/format.js +714 -0
- package/lib/shared/protocol.d.ts +646 -0
- package/lib/shared/protocol.js +129 -0
- package/package.json +85 -4
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Read-only JSON endpoint the browser half reads its data from.
|
|
3
|
+
*
|
|
4
|
+
* ## Why an own HTTP route
|
|
5
|
+
*
|
|
6
|
+
* The harness's typed `ctx.remote` channel needs generated descriptors and is
|
|
7
|
+
* not available to a tree-out-of-tree package, and the shipped `workspaceFiles`
|
|
8
|
+
* Remote is scoped to one Session's workspace while this ledger is
|
|
9
|
+
* cross-workspace by design. A `prefix` route on `ctx.webServer` is the
|
|
10
|
+
* remaining supported carrier — and, unlike the index and `/api` seats, it is
|
|
11
|
+
* NOT behind the browser-cookie fence, so this module owns its own access
|
|
12
|
+
* control:
|
|
13
|
+
*
|
|
14
|
+
* 1. **Loopback `Host` allowlist** — the anti-DNS-rebinding control. A hostile
|
|
15
|
+
* page can point `evil.example` at 127.0.0.1, but it cannot make the browser
|
|
16
|
+
* send `Host: 127.0.0.1:3080`, so the request is rejected here.
|
|
17
|
+
* 2. **`Sec-Fetch-Site` same-origin check** when the browser supplies it.
|
|
18
|
+
* 3. **No CORS headers, ever** — a cross-origin reader cannot see the body even
|
|
19
|
+
* if a request is sent.
|
|
20
|
+
* 4. **GET/HEAD only, read-only payload** — there is no mutation surface.
|
|
21
|
+
*
|
|
22
|
+
* The endpoint serves token totals, model ids, and workspace directory names.
|
|
23
|
+
* It never serves prompts, messages, credentials, or file contents.
|
|
24
|
+
*
|
|
25
|
+
* @module dsh-token-usage-ledger/host/api
|
|
26
|
+
*/
|
|
27
|
+
import type { IncomingMessage, ServerResponse } from 'node:http';
|
|
28
|
+
import type { BackfillResult, BackupFile, ImportResult, SummaryResponse } from '../shared/protocol.js';
|
|
29
|
+
/**
|
|
30
|
+
* The host's own browser-trust + authentication fence.
|
|
31
|
+
*
|
|
32
|
+
* When the composition provides one (`ctx.connection.requestRejection`), it is
|
|
33
|
+
* the AUTHORITY: it applies the deployment's trusted-host/authority policy and
|
|
34
|
+
* verifies the signed browser-session cookie, which this plugin cannot do on its
|
|
35
|
+
* own. The local checks below then step aside rather than double-rejecting
|
|
36
|
+
* traffic the deployment deliberately allows.
|
|
37
|
+
*/
|
|
38
|
+
/** Header view a fence consumes. */
|
|
39
|
+
export type TrustHeaders = Readonly<Record<string, string | readonly string[] | undefined>>;
|
|
40
|
+
export type RequestFence = (request: {
|
|
41
|
+
headers: TrustHeaders;
|
|
42
|
+
}) => 401 | 403 | undefined;
|
|
43
|
+
/** Access-control settings the route enforces. */
|
|
44
|
+
export interface ApiAccessOptions {
|
|
45
|
+
/** Extra host names to accept in addition to loopback (fallback mode only). */
|
|
46
|
+
extraAllowedHosts: readonly string[];
|
|
47
|
+
/**
|
|
48
|
+
* Accept any `Host`. Disables the fallback anti-rebinding control; only for a
|
|
49
|
+
* deployment deliberately served to other machines and with no fence.
|
|
50
|
+
*/
|
|
51
|
+
allowAnyHost: boolean;
|
|
52
|
+
/**
|
|
53
|
+
* Resolve the host's fence FOR ONE REQUEST.
|
|
54
|
+
*
|
|
55
|
+
* Resolution is per-request rather than at registration time on purpose: the
|
|
56
|
+
* connection service is contributed by another row, and whether it exists yet
|
|
57
|
+
* when this route registers is a composition-order accident. Reading it when a
|
|
58
|
+
* request actually arrives is order-independent, and `undefined` keeps the
|
|
59
|
+
* plugin's own checks in charge.
|
|
60
|
+
*/
|
|
61
|
+
fenceFor?: ((request: {
|
|
62
|
+
headers: TrustHeaders;
|
|
63
|
+
}) => RequestFence | undefined) | undefined;
|
|
64
|
+
}
|
|
65
|
+
/** Collaborators the route needs. */
|
|
66
|
+
export interface ApiDeps {
|
|
67
|
+
/** Path prefix the route is registered under, without a trailing slash. */
|
|
68
|
+
prefix: string;
|
|
69
|
+
/** Produce the summary for one parsed query. */
|
|
70
|
+
summarize: (query: SummaryQuery) => Promise<SummaryResponse>;
|
|
71
|
+
/** Build the full downloadable backup envelope. */
|
|
72
|
+
exportBackup: () => Promise<BackupFile>;
|
|
73
|
+
/** Validate + append records from a parsed backup body. */
|
|
74
|
+
importBackup: (body: unknown) => Promise<ImportResult>;
|
|
75
|
+
/** Scan session logs; the caller writes only when `dryRun` is false. */
|
|
76
|
+
backfill: (dryRun: boolean) => Promise<BackfillResult>;
|
|
77
|
+
/** Report an internal failure; the response body stays generic. */
|
|
78
|
+
warn: (message: string) => void;
|
|
79
|
+
/** Access-control settings. */
|
|
80
|
+
access: ApiAccessOptions;
|
|
81
|
+
}
|
|
82
|
+
/** Parsed and validated query for the summary endpoint. */
|
|
83
|
+
export interface SummaryQuery {
|
|
84
|
+
/** Workspace key to filter by, or `null`. */
|
|
85
|
+
workspace: string | null;
|
|
86
|
+
/** Model key (provider/model) to filter by, or `null`. */
|
|
87
|
+
model: string | null;
|
|
88
|
+
/** Provider id to filter by, or `null`. */
|
|
89
|
+
provider: string | null;
|
|
90
|
+
/** Width of the daily window in days, already clamped. */
|
|
91
|
+
days: number;
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* Report whether a request's `Host` header is acceptable.
|
|
95
|
+
*
|
|
96
|
+
* @param hostHeader - raw `Host` value, possibly with a port.
|
|
97
|
+
* @param access - access-control settings.
|
|
98
|
+
* @returns true when the request may proceed.
|
|
99
|
+
*/
|
|
100
|
+
export declare function hostAllowed(hostHeader: string | undefined, access: ApiAccessOptions): boolean;
|
|
101
|
+
/**
|
|
102
|
+
* Parse the summary query string.
|
|
103
|
+
*
|
|
104
|
+
* Unknown parameters are ignored, an empty value means "no filter", and `days`
|
|
105
|
+
* is clamped into the supported range instead of being rejected — a bad query
|
|
106
|
+
* degrades to the default view rather than to an error page.
|
|
107
|
+
*
|
|
108
|
+
* @param search - raw query string including the leading `?`.
|
|
109
|
+
* @returns the validated query.
|
|
110
|
+
*/
|
|
111
|
+
export declare function parseSummaryQuery(search: string): SummaryQuery;
|
|
112
|
+
/**
|
|
113
|
+
* Build the route handler.
|
|
114
|
+
*
|
|
115
|
+
* @param deps - prefix, summarizer, warning sink, and access settings.
|
|
116
|
+
* @returns a handler suitable for `ctx.webServer.register({ kind: 'prefix', … })`.
|
|
117
|
+
*/
|
|
118
|
+
export declare function createRouteHandler(deps: ApiDeps): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
|
package/lib/host/api.js
ADDED
|
@@ -0,0 +1,346 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Read-only JSON endpoint the browser half reads its data from.
|
|
3
|
+
*
|
|
4
|
+
* ## Why an own HTTP route
|
|
5
|
+
*
|
|
6
|
+
* The harness's typed `ctx.remote` channel needs generated descriptors and is
|
|
7
|
+
* not available to a tree-out-of-tree package, and the shipped `workspaceFiles`
|
|
8
|
+
* Remote is scoped to one Session's workspace while this ledger is
|
|
9
|
+
* cross-workspace by design. A `prefix` route on `ctx.webServer` is the
|
|
10
|
+
* remaining supported carrier — and, unlike the index and `/api` seats, it is
|
|
11
|
+
* NOT behind the browser-cookie fence, so this module owns its own access
|
|
12
|
+
* control:
|
|
13
|
+
*
|
|
14
|
+
* 1. **Loopback `Host` allowlist** — the anti-DNS-rebinding control. A hostile
|
|
15
|
+
* page can point `evil.example` at 127.0.0.1, but it cannot make the browser
|
|
16
|
+
* send `Host: 127.0.0.1:3080`, so the request is rejected here.
|
|
17
|
+
* 2. **`Sec-Fetch-Site` same-origin check** when the browser supplies it.
|
|
18
|
+
* 3. **No CORS headers, ever** — a cross-origin reader cannot see the body even
|
|
19
|
+
* if a request is sent.
|
|
20
|
+
* 4. **GET/HEAD only, read-only payload** — there is no mutation surface.
|
|
21
|
+
*
|
|
22
|
+
* The endpoint serves token totals, model ids, and workspace directory names.
|
|
23
|
+
* It never serves prompts, messages, credentials, or file contents.
|
|
24
|
+
*
|
|
25
|
+
* @module dsh-token-usage-ledger/host/api
|
|
26
|
+
*/
|
|
27
|
+
import { API_LIMITS, BACKUP_LIMITS } from '../shared/protocol.js';
|
|
28
|
+
import { OperationError } from './operation-error.js';
|
|
29
|
+
/** Exact host names treated as loopback. */
|
|
30
|
+
const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1', '[::1]']);
|
|
31
|
+
/**
|
|
32
|
+
* Report whether a host name is an IPv4 address inside `127.0.0.0/8`.
|
|
33
|
+
* @param host - host name without a port.
|
|
34
|
+
* @returns true for the whole loopback block.
|
|
35
|
+
*/
|
|
36
|
+
function isIpv4Loopback(host) {
|
|
37
|
+
const parts = host.split('.');
|
|
38
|
+
if (parts.length !== 4)
|
|
39
|
+
return false;
|
|
40
|
+
if (parts[0] !== '127')
|
|
41
|
+
return false;
|
|
42
|
+
return parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255);
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Report whether a request's `Host` header is acceptable.
|
|
46
|
+
*
|
|
47
|
+
* @param hostHeader - raw `Host` value, possibly with a port.
|
|
48
|
+
* @param access - access-control settings.
|
|
49
|
+
* @returns true when the request may proceed.
|
|
50
|
+
*/
|
|
51
|
+
export function hostAllowed(hostHeader, access) {
|
|
52
|
+
if (access.allowAnyHost)
|
|
53
|
+
return true;
|
|
54
|
+
if (hostHeader === undefined || hostHeader.length === 0)
|
|
55
|
+
return false;
|
|
56
|
+
const host = stripPort(hostHeader.trim().toLowerCase());
|
|
57
|
+
if (LOOPBACK_HOSTS.has(host) || isIpv4Loopback(host))
|
|
58
|
+
return true;
|
|
59
|
+
for (const extra of access.extraAllowedHosts) {
|
|
60
|
+
// The configured entry matches by HOST NAME, and its own port is ignored:
|
|
61
|
+
// pinning `harness.internal:3080` must not silently widen to any port on
|
|
62
|
+
// that name, which is what stripping both sides used to do.
|
|
63
|
+
if (stripPort(extra.trim().toLowerCase()) === host)
|
|
64
|
+
return true;
|
|
65
|
+
}
|
|
66
|
+
return false;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* Remove a trailing `:port` from a host value, leaving IPv6 literals intact.
|
|
70
|
+
* @param value - host value.
|
|
71
|
+
* @returns the host without its port.
|
|
72
|
+
*/
|
|
73
|
+
function stripPort(value) {
|
|
74
|
+
if (value.startsWith('[')) {
|
|
75
|
+
const end = value.indexOf(']');
|
|
76
|
+
return end === -1 ? value : value.slice(0, end + 1);
|
|
77
|
+
}
|
|
78
|
+
const colon = value.lastIndexOf(':');
|
|
79
|
+
// A bare IPv6 literal has several colons; only a single-colon value carries a port.
|
|
80
|
+
if (colon === -1 || value.indexOf(':') !== colon)
|
|
81
|
+
return value;
|
|
82
|
+
// Only a NUMERIC suffix is a port. Anything else is a malformed authority, and
|
|
83
|
+
// returning its head would let `127.0.0.1:3080#@evil` pass as loopback.
|
|
84
|
+
const suffix = value.slice(colon + 1);
|
|
85
|
+
return /^\d{1,5}$/.test(suffix) ? value.slice(0, colon) : value;
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* Parse the summary query string.
|
|
89
|
+
*
|
|
90
|
+
* Unknown parameters are ignored, an empty value means "no filter", and `days`
|
|
91
|
+
* is clamped into the supported range instead of being rejected — a bad query
|
|
92
|
+
* degrades to the default view rather than to an error page.
|
|
93
|
+
*
|
|
94
|
+
* @param search - raw query string including the leading `?`.
|
|
95
|
+
* @returns the validated query.
|
|
96
|
+
*/
|
|
97
|
+
export function parseSummaryQuery(search) {
|
|
98
|
+
const params = new URLSearchParams(search);
|
|
99
|
+
const workspace = nonEmpty(params.get('workspace'));
|
|
100
|
+
const model = nonEmpty(params.get('model'));
|
|
101
|
+
const provider = nonEmpty(params.get('provider'));
|
|
102
|
+
const raw = params.get('days');
|
|
103
|
+
// An ABSENT parameter must fall back to the default, not to `Number(null)`,
|
|
104
|
+
// which is 0 and would silently collapse the window to a single day.
|
|
105
|
+
const parsed = raw === null ? Number.NaN : Number(raw);
|
|
106
|
+
const days = Number.isFinite(parsed)
|
|
107
|
+
? Math.min(API_LIMITS.maxDays, Math.max(1, Math.trunc(parsed)))
|
|
108
|
+
: API_LIMITS.defaultDays;
|
|
109
|
+
return { workspace, model, provider, days };
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* Normalize an optional query value.
|
|
113
|
+
* @param value - raw parameter.
|
|
114
|
+
* @returns the trimmed value, or `null` when absent or blank.
|
|
115
|
+
*/
|
|
116
|
+
function nonEmpty(value) {
|
|
117
|
+
if (value === null)
|
|
118
|
+
return null;
|
|
119
|
+
const trimmed = value.trim();
|
|
120
|
+
return trimmed.length === 0 ? null : trimmed;
|
|
121
|
+
}
|
|
122
|
+
/**
|
|
123
|
+
* Build the route handler.
|
|
124
|
+
*
|
|
125
|
+
* @param deps - prefix, summarizer, warning sink, and access settings.
|
|
126
|
+
* @returns a handler suitable for `ctx.webServer.register({ kind: 'prefix', … })`.
|
|
127
|
+
*/
|
|
128
|
+
export function createRouteHandler(deps) {
|
|
129
|
+
const paths = {
|
|
130
|
+
summary: `${deps.prefix}/api/summary`,
|
|
131
|
+
export: `${deps.prefix}/api/export`,
|
|
132
|
+
import: `${deps.prefix}/api/import`,
|
|
133
|
+
backfill: `${deps.prefix}/api/backfill`,
|
|
134
|
+
};
|
|
135
|
+
return async (req, res) => {
|
|
136
|
+
try {
|
|
137
|
+
await handle(req, res, deps, paths);
|
|
138
|
+
}
|
|
139
|
+
catch (error) {
|
|
140
|
+
if (error instanceof OperationError) {
|
|
141
|
+
// Structured, already user-safe: no stack/path/record contents.
|
|
142
|
+
if (!res.headersSent)
|
|
143
|
+
sendError(res, error.status, error.code, error.message);
|
|
144
|
+
else
|
|
145
|
+
res.end();
|
|
146
|
+
return;
|
|
147
|
+
}
|
|
148
|
+
deps.warn(`token-usage api: unhandled request failure: ${error instanceof Error ? error.message : String(error)}`);
|
|
149
|
+
if (!res.headersSent)
|
|
150
|
+
sendError(res, 500, 'internal', 'internal error');
|
|
151
|
+
else
|
|
152
|
+
res.end();
|
|
153
|
+
}
|
|
154
|
+
};
|
|
155
|
+
}
|
|
156
|
+
/**
|
|
157
|
+
* Serve one request.
|
|
158
|
+
* @param req - incoming request.
|
|
159
|
+
* @param res - response to own.
|
|
160
|
+
* @param deps - route dependencies.
|
|
161
|
+
* @param summaryPath - exact summary path.
|
|
162
|
+
*/
|
|
163
|
+
async function handle(req, res, deps, paths) {
|
|
164
|
+
const method = req.method ?? 'GET';
|
|
165
|
+
if (method !== 'GET' && method !== 'HEAD' && method !== 'POST') {
|
|
166
|
+
sendError(res, 405, 'method-not-allowed', 'only GET, HEAD and POST are supported');
|
|
167
|
+
return;
|
|
168
|
+
}
|
|
169
|
+
const fence = deps.access.fenceFor?.(req);
|
|
170
|
+
if (fence !== undefined) {
|
|
171
|
+
// The host fence is authoritative: it knows the deployment's trusted hosts
|
|
172
|
+
// AND whether this browser holds a valid session.
|
|
173
|
+
let rejection;
|
|
174
|
+
try {
|
|
175
|
+
rejection = fence({ headers: req.headers });
|
|
176
|
+
}
|
|
177
|
+
catch (error) {
|
|
178
|
+
// A fence that cannot answer must not open the route.
|
|
179
|
+
deps.warn(`token-usage api: trust fence failed, refusing the request: ${error instanceof Error ? error.message : String(error)}`);
|
|
180
|
+
rejection = 403;
|
|
181
|
+
}
|
|
182
|
+
if (rejection !== undefined) {
|
|
183
|
+
sendError(res, rejection, rejection === 401 ? 'unauthenticated' : 'untrusted-request', rejection === 401 ? 'authentication required' : 'request not trusted');
|
|
184
|
+
return;
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
else {
|
|
188
|
+
// Fallback mode: no fence in this composition, so the plugin's own controls
|
|
189
|
+
// are the access control. They defeat DNS rebinding and cross-site reads but
|
|
190
|
+
// do NOT authenticate — see README §6.
|
|
191
|
+
if (!hostAllowed(req.headers.host, deps.access)) {
|
|
192
|
+
deps.warn(`token-usage api: rejected request with Host ${JSON.stringify(req.headers.host ?? '')}`);
|
|
193
|
+
sendError(res, 403, 'host-not-allowed', 'host not allowed');
|
|
194
|
+
return;
|
|
195
|
+
}
|
|
196
|
+
const fetchSite = req.headers['sec-fetch-site'];
|
|
197
|
+
if (typeof fetchSite === 'string' && fetchSite !== 'same-origin' && fetchSite !== 'none') {
|
|
198
|
+
sendError(res, 403, 'cross-site', 'cross-site requests are not served');
|
|
199
|
+
return;
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
// A write initiated by another site must never reach the data endpoints even
|
|
203
|
+
// when a fence is present: the browser label is cheap to check and a same-site
|
|
204
|
+
// JSON POST cannot be forged by a cross-site form.
|
|
205
|
+
if (method === 'POST') {
|
|
206
|
+
const fetchSite = req.headers['sec-fetch-site'];
|
|
207
|
+
if (typeof fetchSite === 'string' && fetchSite !== 'same-origin' && fetchSite !== 'none') {
|
|
208
|
+
sendError(res, 403, 'cross-site', 'cross-site requests are not served');
|
|
209
|
+
return;
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
const url = new URL(req.url ?? '/', 'http://placeholder.invalid');
|
|
213
|
+
const path = url.pathname;
|
|
214
|
+
const allowed = {
|
|
215
|
+
[paths.summary]: ['GET', 'HEAD'],
|
|
216
|
+
[paths.export]: ['GET', 'HEAD'],
|
|
217
|
+
[paths.import]: ['POST'],
|
|
218
|
+
[paths.backfill]: ['POST'],
|
|
219
|
+
};
|
|
220
|
+
const methods = allowed[path];
|
|
221
|
+
if (methods === undefined) {
|
|
222
|
+
sendError(res, 404, 'not-found', 'unknown endpoint');
|
|
223
|
+
return;
|
|
224
|
+
}
|
|
225
|
+
if (!methods.includes(method)) {
|
|
226
|
+
sendError(res, 405, 'method-not-allowed', 'method not allowed for this endpoint');
|
|
227
|
+
return;
|
|
228
|
+
}
|
|
229
|
+
if (path === paths.summary) {
|
|
230
|
+
const query = parseSummaryQuery(url.search);
|
|
231
|
+
const summary = await deps.summarize(query);
|
|
232
|
+
sendJson(req, res, 200, summary);
|
|
233
|
+
return;
|
|
234
|
+
}
|
|
235
|
+
if (path === paths.export) {
|
|
236
|
+
const backup = await deps.exportBackup();
|
|
237
|
+
sendJson(req, res, 200, backup, {
|
|
238
|
+
'content-disposition': `attachment; filename="token-usage-backup-${new Date().toISOString().slice(0, 10)}.json"`,
|
|
239
|
+
});
|
|
240
|
+
return;
|
|
241
|
+
}
|
|
242
|
+
const contentType = req.headers['content-type'];
|
|
243
|
+
if (typeof contentType !== 'string' || !contentType.toLowerCase().startsWith('application/json')) {
|
|
244
|
+
sendError(res, 415, 'unsupported-format', 'content-type must be application/json');
|
|
245
|
+
return;
|
|
246
|
+
}
|
|
247
|
+
const body = await readJsonBody(req, BACKUP_LIMITS.maxBytes);
|
|
248
|
+
if (body.ok === false) {
|
|
249
|
+
sendError(res, body.status, body.code, body.message);
|
|
250
|
+
return;
|
|
251
|
+
}
|
|
252
|
+
if (path === paths.import) {
|
|
253
|
+
const result = await deps.importBackup(body.value);
|
|
254
|
+
sendJson(req, res, 200, result);
|
|
255
|
+
return;
|
|
256
|
+
}
|
|
257
|
+
// Backfill: the body is optional for a write run; an explicit object is
|
|
258
|
+
// required so an accidental empty POST cannot start a disk scan/write.
|
|
259
|
+
if (typeof body.value !== 'object' || body.value === null || Array.isArray(body.value)) {
|
|
260
|
+
sendError(res, 400, 'invalid-argument', 'backfill body must be a JSON object');
|
|
261
|
+
return;
|
|
262
|
+
}
|
|
263
|
+
const dryRun = body.value.dryRun === true;
|
|
264
|
+
const result = await deps.backfill(dryRun);
|
|
265
|
+
sendJson(req, res, 200, result);
|
|
266
|
+
}
|
|
267
|
+
/**
|
|
268
|
+
* Read a bounded JSON request body.
|
|
269
|
+
*
|
|
270
|
+
* A missing/invalid body is a client error; an oversized body is rejected
|
|
271
|
+
* before it can be fully buffered. The handler never echoes the body.
|
|
272
|
+
*
|
|
273
|
+
* @param req - incoming request.
|
|
274
|
+
* @param maxBytes - maximum accepted bytes.
|
|
275
|
+
* @returns the parsed value or a structured failure.
|
|
276
|
+
*/
|
|
277
|
+
async function readJsonBody(req, maxBytes) {
|
|
278
|
+
const declared = req.headers['content-length'];
|
|
279
|
+
if (typeof declared === 'string' && /^\d+$/.test(declared) && Number(declared) > maxBytes) {
|
|
280
|
+
req.resume();
|
|
281
|
+
return { ok: false, status: 413, code: 'payload-too-large', message: 'request body is too large' };
|
|
282
|
+
}
|
|
283
|
+
const chunks = [];
|
|
284
|
+
let total = 0;
|
|
285
|
+
try {
|
|
286
|
+
for await (const chunk of req) {
|
|
287
|
+
const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
|
|
288
|
+
total += buffer.length;
|
|
289
|
+
if (total > maxBytes) {
|
|
290
|
+
req.resume();
|
|
291
|
+
return { ok: false, status: 413, code: 'payload-too-large', message: 'request body is too large' };
|
|
292
|
+
}
|
|
293
|
+
chunks.push(buffer);
|
|
294
|
+
}
|
|
295
|
+
}
|
|
296
|
+
catch {
|
|
297
|
+
return { ok: false, status: 400, code: 'invalid-argument', message: 'could not read request body' };
|
|
298
|
+
}
|
|
299
|
+
if (total === 0) {
|
|
300
|
+
return { ok: false, status: 400, code: 'invalid-argument', message: 'request body is empty' };
|
|
301
|
+
}
|
|
302
|
+
try {
|
|
303
|
+
return { ok: true, value: JSON.parse(Buffer.concat(chunks).toString('utf8')) };
|
|
304
|
+
}
|
|
305
|
+
catch {
|
|
306
|
+
return { ok: false, status: 400, code: 'invalid-argument', message: 'request body is not valid JSON' };
|
|
307
|
+
}
|
|
308
|
+
}
|
|
309
|
+
/**
|
|
310
|
+
* Write a JSON response with the hardening headers this route always carries.
|
|
311
|
+
* @param req - request, used to honour HEAD.
|
|
312
|
+
* @param res - response to write.
|
|
313
|
+
* @param status - HTTP status.
|
|
314
|
+
* @param body - JSON-serializable body.
|
|
315
|
+
*/
|
|
316
|
+
function sendJson(req, res, status, body, extraHeaders = {}) {
|
|
317
|
+
const text = JSON.stringify(body);
|
|
318
|
+
res.writeHead(status, {
|
|
319
|
+
'content-type': 'application/json; charset=utf-8',
|
|
320
|
+
'cache-control': 'no-store',
|
|
321
|
+
'x-content-type-options': 'nosniff',
|
|
322
|
+
'referrer-policy': 'no-referrer',
|
|
323
|
+
'content-length': Buffer.byteLength(text),
|
|
324
|
+
...extraHeaders,
|
|
325
|
+
});
|
|
326
|
+
res.end(req.method === 'HEAD' ? undefined : text);
|
|
327
|
+
}
|
|
328
|
+
/**
|
|
329
|
+
* Write an error body in the shared envelope.
|
|
330
|
+
* @param res - response to write.
|
|
331
|
+
* @param status - HTTP status.
|
|
332
|
+
* @param code - stable error code.
|
|
333
|
+
* @param message - human-readable detail.
|
|
334
|
+
*/
|
|
335
|
+
function sendError(res, status, code, message) {
|
|
336
|
+
const body = { ok: false, error: code, message };
|
|
337
|
+
const text = JSON.stringify(body);
|
|
338
|
+
res.writeHead(status, {
|
|
339
|
+
'content-type': 'application/json; charset=utf-8',
|
|
340
|
+
'cache-control': 'no-store',
|
|
341
|
+
'x-content-type-options': 'nosniff',
|
|
342
|
+
'content-length': Buffer.byteLength(text),
|
|
343
|
+
});
|
|
344
|
+
res.end(text);
|
|
345
|
+
}
|
|
346
|
+
//# sourceMappingURL=api.js.map
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Backfill the ledger from durable session logs on disk.
|
|
3
|
+
*
|
|
4
|
+
* The live plugin only sees turns after it is installed; every durable session
|
|
5
|
+
* log contains the same `turn/start`/`turn/end` and settlement events, so a
|
|
6
|
+
* replay through the SAME collector/pricing/record builder produces a line
|
|
7
|
+
* indistinguishable from a live one. This module is shared by the CLI script
|
|
8
|
+
* and the dashboard's 「补录」 button so both use one implementation.
|
|
9
|
+
*
|
|
10
|
+
* @module dsh-token-usage-ledger/host/backfill
|
|
11
|
+
*/
|
|
12
|
+
import type { BackfillReport, UsageRecord } from '../shared/protocol.js';
|
|
13
|
+
import type { PricingRule } from './pricing.js';
|
|
14
|
+
/** Session-log filenames this build understands, newest first. */
|
|
15
|
+
export declare const SESSION_LOG_NAMES: readonly ["session.v4.jsonl.zstd", "session.v3.jsonl.zstd"];
|
|
16
|
+
/** Options for one backfill scan. */
|
|
17
|
+
export interface BackfillOptions {
|
|
18
|
+
/** Harness home containing `sessions/`. */
|
|
19
|
+
home: string;
|
|
20
|
+
/** Ledger file used for the duplicate key/fingerprint sets. */
|
|
21
|
+
ledgerPath: string;
|
|
22
|
+
/** Pricing rule in force (same as the live collector). */
|
|
23
|
+
rule: PricingRule;
|
|
24
|
+
/** Only turns that ENDED on/after this local day key. */
|
|
25
|
+
since?: string | undefined;
|
|
26
|
+
/** Only sessions whose cwd contains this text. */
|
|
27
|
+
workspace?: string | undefined;
|
|
28
|
+
/** Only sessions whose workspace directory name contains this text. */
|
|
29
|
+
lead?: string | undefined;
|
|
30
|
+
/** Maximum session logs to scan (0 = all). */
|
|
31
|
+
limit?: number | undefined;
|
|
32
|
+
/** Fold inherited prefixes too (diagnostic). */
|
|
33
|
+
noPrefilter?: boolean | undefined;
|
|
34
|
+
/** Warning sink for unreadable logs; receives no record contents. */
|
|
35
|
+
onWarning?: ((message: string) => void) | undefined;
|
|
36
|
+
}
|
|
37
|
+
/** Result of one scan: records are returned for the caller to append (or not). */
|
|
38
|
+
export interface BackfillOutcome {
|
|
39
|
+
/** Scan report. */
|
|
40
|
+
report: BackfillReport;
|
|
41
|
+
/** Backfillable records, timestamp-sorted. */
|
|
42
|
+
records: UsageRecord[];
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Scan durable logs and return the missing records.
|
|
46
|
+
*
|
|
47
|
+
* This function never writes; the caller decides whether to append the
|
|
48
|
+
* returned records. It is safe to call repeatedly: the returned set excludes
|
|
49
|
+
* turns already in the ledger and forked copies of them.
|
|
50
|
+
*
|
|
51
|
+
* @param options - home, ledger, pricing rule, filters and warning sink.
|
|
52
|
+
* @returns the report and timestamp-sorted records.
|
|
53
|
+
*/
|
|
54
|
+
export declare function backfillLedger(options: BackfillOptions): Promise<BackfillOutcome>;
|