dsh-ds-balance 1.0.0

package/lib/adapters/http-deepseek-client.js

@@ -0,0 +1,101 @@
+/**
+ * DeepSeek 上游的 HTTP 实现。
+ * @module dsh-ds-balance/adapters/http-deepseek-client
+ */
+import { NetworkError, ParseError, TimeoutError, UpstreamError, classify } from '../domain/errors.js';
+import { parseErrorBody } from '../domain/normalize.js';
+/** 去掉尾部斜杠，避免拼出双斜杠路径。 */
+function joinUrl(baseUrl, path) {
+    return `${baseUrl.replace(/\/+$/, '')}${path}`;
+}
+/** 余额端点路径。 */
+const BALANCE_PATH = '/user/balance';
+/**
+ * 用 WHATWG fetch 调 DeepSeek 的 `GET /user/balance`。
+ *
+ * 超时用自建的 `AbortController + setTimeout`（而不是 `AbortSignal.timeout`），
+ * 这样测试可以在不睡真实时间的前提下驱动超时分支。
+ */
+export class HttpDeepSeekClient {
+    fetchImpl;
+    now;
+    constructor(options = {}) {
+        this.fetchImpl = options.fetchImpl ?? ((input, init) => fetch(input, init));
+        this.now = options.now ?? (() => Date.now());
+    }
+    async fetchBalance(options) {
+        const response = await this.request(options);
+        const text = await response.text();
+        try {
+            return JSON.parse(text);
+        }
+        catch (error) {
+            throw new ParseError('balance response is not JSON', { cause: error });
+        }
+    }
+    async testConnection(options) {
+        const startedAt = this.now();
+        try {
+            const raw = await this.fetchBalance(options);
+            const latencyMs = this.now() - startedAt;
+            const balances = Array.isArray(raw?.balance_infos)
+                ? raw.balance_infos.map((item) => ({ currency: String(item.currency), total: String(item.total_balance) }))
+                : [];
+            return { ok: true, latencyMs, isAvailable: raw?.is_available === true, balances };
+        }
+        catch (error) {
+            const info = classify(error);
+            return { ok: false, latencyMs: this.now() - startedAt, code: info.code, message: info.message };
+        }
+    }
+    /**
+     * 发一次请求并处理状态码。
+     * @throws {UpstreamError} 非 2xx。
+     * @throws {TimeoutError} 超时。
+     * @throws {NetworkError} 连不上。
+     */
+    async request(options) {
+        const controller = new AbortController();
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, options.timeoutMs);
+        const forwardAbort = () => { controller.abort(); };
+        options.signal?.addEventListener('abort', forwardAbort, { once: true });
+        let response;
+        try {
+            response = await this.fetchImpl(joinUrl(options.baseUrl, BALANCE_PATH), {
+                method: 'GET',
+                headers: {
+                    authorization: `Bearer ${options.apiKey}`,
+                    accept: 'application/json',
+                },
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            if (timedOut)
+                throw new TimeoutError(`upstream timeout after ${options.timeoutMs}ms`, { cause: error });
+            if (options.signal?.aborted === true)
+                throw error;
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new TimeoutError(`upstream aborted after ${options.timeoutMs}ms`, { cause: error });
+            }
+            throw new NetworkError(error instanceof Error ? error.message : String(error), { cause: error });
+        }
+        finally {
+            clearTimeout(timer);
+            options.signal?.removeEventListener('abort', forwardAbort);
+        }
+        if (!response.ok) {
+            const text = await response.text().catch(() => '');
+            const parsed = parseErrorBody(text);
+            throw new UpstreamError(response.status, parsed.message ?? parsed.code ?? `upstream ${response.status}`, {
+                headers: response.headers,
+            });
+        }
+        return response;
+    }
+}
+//# sourceMappingURL=http-deepseek-client.js.map

package/lib/adapters/memory-metrics.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 内存指标登记表。
+ *
+ * dsh 的默认组合里**没有指标 sink**，所以这个实现把聚合值留在内存里，
+ * 由 `GET /api/v1/healthz` 的 `metrics` 段暴露出去 —— 否则 §12 的四个指标
+ * 就只是「调用了一个空函数」，谁也看不见。
+ *
+ * 键的构造规则：`名字{标签=值,...}`，标签按键名排序，保证同一组标签得到同一个键。
+ * @module dsh-ds-balance/adapters/memory-metrics
+ */
+import type { Metrics, MetricsSnapshot } from '../ports/metrics.js';
+/**
+ * 组装指标键。
+ * @param name - 指标名。
+ * @param labels - 标签；省略或为空时键就是名字本身。
+ * @returns 稳定的键。
+ */
+export declare function metricKey(name: string, labels?: Record<string, string>): string;
+/** 内存指标登记表。 */
+export declare class MemoryMetrics implements Metrics {
+    private readonly counters;
+    private readonly gauges;
+    private readonly histograms;
+    counter(name: string, labels?: Record<string, string>): void;
+    gauge(name: string, labels: Record<string, string>, value: number): void;
+    histogram(name: string, labels: Record<string, string>, value: number): void;
+    /** 当前聚合值的一份拷贝。 */
+    snapshot(): MetricsSnapshot;
+}
+//# sourceMappingURL=memory-metrics.d.ts.map

package/lib/adapters/memory-metrics.js

@@ -0,0 +1,67 @@
+/**
+ * 内存指标登记表。
+ *
+ * dsh 的默认组合里**没有指标 sink**，所以这个实现把聚合值留在内存里，
+ * 由 `GET /api/v1/healthz` 的 `metrics` 段暴露出去 —— 否则 §12 的四个指标
+ * 就只是「调用了一个空函数」，谁也看不见。
+ *
+ * 键的构造规则：`名字{标签=值,...}`，标签按键名排序，保证同一组标签得到同一个键。
+ * @module dsh-ds-balance/adapters/memory-metrics
+ */
+/** 键与标签值里不能出现的字符。出现时替换成下划线，避免键互相吞并。 */
+const UNSAFE = /[^A-Za-z0-9_.:-]/g;
+/** 转义一段键或标签值。 */
+function escape(part) {
+    return part.replace(UNSAFE, '_');
+}
+/**
+ * 组装指标键。
+ * @param name - 指标名。
+ * @param labels - 标签；省略或为空时键就是名字本身。
+ * @returns 稳定的键。
+ */
+export function metricKey(name, labels) {
+    const entries = Object.entries(labels ?? {});
+    if (entries.length === 0)
+        return escape(name);
+    const rendered = entries
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([key, value]) => `${escape(key)}=${escape(value)}`)
+        .join(',');
+    return `${escape(name)}{${rendered}}`;
+}
+/** 内存指标登记表。 */
+export class MemoryMetrics {
+    counters = new Map();
+    gauges = new Map();
+    histograms = new Map();
+    counter(name, labels) {
+        const key = metricKey(name, labels);
+        this.counters.set(key, (this.counters.get(key) ?? 0) + 1);
+    }
+    gauge(name, labels, value) {
+        this.gauges.set(metricKey(name, labels), value);
+    }
+    histogram(name, labels, value) {
+        const key = metricKey(name, labels);
+        const current = this.histograms.get(key);
+        this.histograms.set(key, current === undefined
+            ? { count: 1, sum: value, min: value, max: value, last: value }
+            : {
+                count: current.count + 1,
+                sum: current.sum + value,
+                min: Math.min(current.min, value),
+                max: Math.max(current.max, value),
+                last: value,
+            });
+    }
+    /** 当前聚合值的一份拷贝。 */
+    snapshot() {
+        return {
+            counters: Object.fromEntries(this.counters),
+            gauges: Object.fromEntries(this.gauges),
+            histograms: Object.fromEntries([...this.histograms].map(([key, value]) => [key, { ...value }])),
+        };
+    }
+}
+//# sourceMappingURL=memory-metrics.js.map

package/lib/adapters/salt-file.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 服务端盐的读写。
+ *
+ * `accountTag` 由它派生，所以**它丢了账本就会孤立**：见 docs/backend-architecture.md §19 第 5 条。
+ * 文件权限 0600；路径由组装点用 `@deepseek-ai/dsh-home-paths` 的 `dshHomePath()` 拼出来。
+ * @module dsh-ds-balance/adapters/salt-file
+ */
+/** 盐的字节数与编码。 */
+export declare const SALT_BYTES = 32;
+export declare const SALT_ENCODING: "hex";
+/** 构造参数。 */
+export interface SaltFileOptions {
+    /** 盐文件绝对路径。 */
+    path: string;
+    /** 注入随机源，测试用。 */
+    random?: (bytes: number) => string;
+    /** 注入读，测试用。 */
+    read?: (path: string) => Promise<string>;
+    /** 注入写，测试用。 */
+    write?: (path: string, data: string, mode: number) => Promise<void>;
+    /** 注入建目录，测试用。 */
+    makeDir?: (path: string) => Promise<void>;
+}
+/**
+ * 读取盐；不存在则生成并落盘。
+ *
+ * 空文件与空白内容视为缺失（与 `$DSH_HOME` 的空白处理保持一致）。
+ * @param options - 路径与可注入依赖。
+ * @returns 十六进制盐字符串。
+ */
+export declare function loadOrCreateSalt(options: SaltFileOptions): Promise<string>;
+//# sourceMappingURL=salt-file.d.ts.map

package/lib/adapters/salt-file.js

@@ -0,0 +1,40 @@
+/**
+ * 服务端盐的读写。
+ *
+ * `accountTag` 由它派生，所以**它丢了账本就会孤立**：见 docs/backend-architecture.md §19 第 5 条。
+ * 文件权限 0600；路径由组装点用 `@deepseek-ai/dsh-home-paths` 的 `dshHomePath()` 拼出来。
+ * @module dsh-ds-balance/adapters/salt-file
+ */
+import { randomBytes } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/** 盐的字节数与编码。 */
+export const SALT_BYTES = 32;
+export const SALT_ENCODING = 'hex';
+/**
+ * 读取盐；不存在则生成并落盘。
+ *
+ * 空文件与空白内容视为缺失（与 `$DSH_HOME` 的空白处理保持一致）。
+ * @param options - 路径与可注入依赖。
+ * @returns 十六进制盐字符串。
+ */
+export async function loadOrCreateSalt(options) {
+    const read = options.read ?? (async (path) => readFile(path, 'utf8'));
+    const write = options.write ?? (async (path, data, mode) => writeFile(path, data, { mode }));
+    const makeDir = options.makeDir ?? (async (path) => { await mkdir(path, { recursive: true }); });
+    const random = options.random ?? ((bytes) => randomBytes(bytes).toString(SALT_ENCODING));
+    try {
+        const existing = (await read(options.path)).trim();
+        if (existing !== '')
+            return existing;
+    }
+    catch {
+        // 不存在或读不动：落到生成分支。
+    }
+    const created = random(SALT_BYTES);
+    await makeDir(dirname(options.path));
+    // 0600：只有本用户可读写。
+    await write(options.path, created, 0o600);
+    return created;
+}
+//# sourceMappingURL=salt-file.js.map