* docs(serve): v0.16-alpha known limits + SDK QWEN_SERVER_TOKEN env fallback (PR 27) First PR in the F5 release chain (PR 27 → 28 → 30a → 31) per the 2026-05-24 v0.16-alpha scope freeze in #4175 (text-only chat / coding + local-only deployment). ## SDK ergonomic micro-change (~50 LOC + 4 tests) `DaemonClient` constructor falls back to `QWEN_SERVER_TOKEN` env var when `opts.token` is absent — closes the asymmetry where the daemon side already honors this var (--token CLI flag fallback, already in main since PR 15) but the SDK forced clients to thread it through every construction. Properties: - Browser-safe via `globalThis.process` indirection (the SDK is imported by @qwen-code/webui; literal process.env access would explode at module load on browser bundles) - Whitespace stripped (matches daemon-side trim — handy for `export QWEN_SERVER_TOKEN=\"\$(cat token.txt)\"` where cat adds a trailing newline) - Empty / whitespace-only treated as unset (a stale `export QWEN_SERVER_TOKEN=\"\"` won't accidentally send Authorization: Bearer with no token) - Resolved at construction, not lazily per-request (later process.env mutations don't affect already-built clients) - Explicit opts.token wins over env Tests: 4 new in DaemonClient.test.ts `bearer auth` describe covering env fallback / explicit-wins / empty-treated-unset / whitespace-stripped. Plus a defensive snapshot/restore on the existing 'omits Authorization when no token' test so an inherited test-runner export of QWEN_SERVER_TOKEN doesn't turn that assertion into a false positive. This SDK fallback is the entire ergonomic replacement for PR 29's SDK env/file fallback. PR 29's other features (auto-gen daemon token, instance-path keying, stale cleanup) remain deferred to v0.16.x — all are DX improvements over the boot-time security gate already shipped in PR 15. ## v0.16-alpha docs (~120 LOC markdown) - docs/users/qwen-serve.md: new "v0.16-alpha known limits" section enumerating product surface (text-only ✅, multimodal ❌), deployment surface (local launchers ✅, containerized ❌, multi- daemon ❌, BYO-token ✅), and hardening posture (boot security gate ✅, mutation gate ✅, MCP guardrails ✅, prompt absolute deadline ⏸️, rate limiting ⏸️, --max-body-size ⏸️). Adds an alpha banner at the top of the file. - docs/developers/examples/daemon-client-quickstart.md: documents the SDK env fallback in both the Hello-daemon intro and the Authentication section, with the "export + no-token-arg" recommended path called out for local dev. Verification: 125/125 DaemonClient.test.ts pass (121 existing + 4 new); 4/4 daemon-public-surface.test.ts pass (constructor signature unchanged); tsc clean on packages/sdk-typescript; eslint --max-warnings 0 clean on touched .ts files. Part of #4175. * fix(sdk): #4473 round 1 fold-in — 2 copilot doc threads adopted T1 [copilot DaemonClient.ts:144 — stale line refs in readTokenFromEnv JSDoc]: removed `runQwenServe.ts:175` (token resolution actually lives at line 302-318 today, would drift again on next refactor) and `docs/users/qwen-serve.md:173`. Replaced with stable symbol/section references ("runQwenServe token-resolution path"; "qwen-serve user guide CLI flags section"). T2 [copilot daemon-client-quickstart.md:33 — `~/.qwen/server-token` implies built-in path that doesn't exist]: PR 27 explicitly defers token auto-generation + file-store fallback (PR 29 deferred features). The example incorrectly suggested a standard file location. Replaced with two explicit user-managed alternatives: - `openssl rand -hex 32` one-shot - `cat ./my-token-file` user-managed file Both threads were accurate suggestions caught at the right time (zero behavior change; pure docstring/example accuracy). Verification: 125/125 DaemonClient tests pass; tsc + eslint clean on touched files.
125 lines
3.4 KiB
JavaScript
125 lines
3.4 KiB
JavaScript
/**
|
|
* @license
|
|
* Copyright 2026 Qwen Team
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*/
|
|
|
|
import crypto from 'node:crypto';
|
|
import fs from 'node:fs';
|
|
import path from 'node:path';
|
|
import { pipeline } from 'node:stream/promises';
|
|
import { fileURLToPath } from 'node:url';
|
|
|
|
export function fail(message) {
|
|
throw new Error(`ERROR: ${message}`);
|
|
}
|
|
|
|
export async function sha256File(filePath) {
|
|
const hash = crypto.createHash('sha256');
|
|
await pipeline(fs.createReadStream(filePath), hash);
|
|
return hash.digest('hex');
|
|
}
|
|
|
|
/**
|
|
* Parse a SHA256SUMS file. Handles:
|
|
* - optional leading UTF-8 BOM (uploaded via Windows tools)
|
|
* - binary-prefix markers (`*` before filename)
|
|
* - empty lines and CRLF / LF line endings
|
|
*/
|
|
export function parseSha256Sums(content) {
|
|
// Strip a leading UTF-8 BOM so a SHA256SUMS file uploaded via a Windows tool
|
|
// that prepends one still reports a useful "Missing checksum entry" error
|
|
// instead of "Malformed SHA256SUMS line 1".
|
|
const normalized = content.replace(/^\uFEFF/, '');
|
|
const checksums = new Map();
|
|
for (const [index, line] of normalized.split(/\r?\n/).entries()) {
|
|
const trimmed = line.trim();
|
|
if (!trimmed) {
|
|
continue;
|
|
}
|
|
|
|
const match = /^([0-9a-fA-F]{64})\s+\*?(.+)$/.exec(trimmed);
|
|
if (!match) {
|
|
fail(`Malformed SHA256SUMS line ${index + 1}: ${trimmed}`);
|
|
}
|
|
if (checksums.has(match[2])) {
|
|
fail(`Duplicate SHA256SUMS entry for: ${match[2]}`);
|
|
}
|
|
checksums.set(match[2], match[1].toLowerCase());
|
|
}
|
|
return checksums;
|
|
}
|
|
|
|
export function readOptionValue(argv, index, optionName) {
|
|
const value = argv[index + 1];
|
|
if (!value || value.startsWith('-')) {
|
|
fail(`${optionName} requires a value`);
|
|
}
|
|
return value;
|
|
}
|
|
|
|
export function isMainModule(importMetaUrl) {
|
|
const filename = fileURLToPath(importMetaUrl);
|
|
return process.argv[1] && path.resolve(process.argv[1]) === filename;
|
|
}
|
|
|
|
/**
|
|
* Parse CLI arguments. Supports:
|
|
* - --flag → args[def.key] = true
|
|
* - --key value → args[def.key] = value
|
|
* - --key=value → args[def.key] = value
|
|
* - -h, --help → args.help = true (always recognised)
|
|
*
|
|
* @param {string[]} argv
|
|
* @param {Record<string, {key: string, type: 'flag'|'value'}>} definitions
|
|
* @returns {{help: false} & Record<string, any>}
|
|
*/
|
|
export function parseArgs(argv, definitions) {
|
|
const args = { help: false };
|
|
|
|
for (let index = 0; index < argv.length; index += 1) {
|
|
const raw = argv[index];
|
|
if (raw === '--help' || raw === '-h') {
|
|
args.help = true;
|
|
continue;
|
|
}
|
|
|
|
// --key=value form
|
|
const eqIndex = raw.indexOf('=');
|
|
if (eqIndex >= 0) {
|
|
const key = raw.slice(0, eqIndex);
|
|
const value = raw.slice(eqIndex + 1);
|
|
if (key === '--help' || key === '-h') {
|
|
fail(`${key} does not accept a value`);
|
|
}
|
|
const def = definitions[key];
|
|
if (!def) {
|
|
fail(`Unknown option: ${key}`);
|
|
}
|
|
if (def.type === 'flag') {
|
|
fail(`${key} does not accept a value`);
|
|
}
|
|
if (!value || value.startsWith('-')) {
|
|
fail(`${key} requires a value`);
|
|
}
|
|
args[def.key] = value;
|
|
continue;
|
|
}
|
|
|
|
const def = definitions[raw];
|
|
if (!def) {
|
|
fail(`Unknown option: ${raw}`);
|
|
}
|
|
|
|
if (def.type === 'flag') {
|
|
args[def.key] = true;
|
|
continue;
|
|
}
|
|
|
|
args[def.key] = readOptionValue(argv, index, raw);
|
|
index += 1;
|
|
}
|
|
|
|
return args;
|
|
}
|