diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 57ad8d3..4f786d3 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -18,4 +18,4 @@ jobs: cache: npm - run: npm ci --ignore-scripts - run: npm test - - run: npm pack --dry-run + - run: npm run test:packed diff --git a/.gitignore b/.gitignore index e871be6..13bd5cb 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,5 @@ dist/ *.js.map .env .env.local +.test-tmp/ +.npm-cache/ diff --git a/CHANGELOG.md b/CHANGELOG.md index f587d50..4d79477 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,14 @@ ## 0.2.0 +- Breaking: require a caller-known request_id on both generation tools and the client generate method. +- Add the local, credential-free flowspeech_new_request_id tool; allow flowspeech_get_job lookup by request UUID. +- Validate allowed fields, types and output paths before paid submission; preserve atomic no-overwrite and recovery IDs on save failures. +- Preserve caller-known recovery across MCP timeout/cancellation without cancelling paid server jobs. +- Validate all result metadata, usage, normalized request/job correlation and complete PCM WAV chunk structure. +- Honor received Retry-After after interrupted bodies and enforce at least five seconds on status retries. +- Run source and stdio regressions again against the inspected packed artifact before publishing. + - Migrate generation to public API v1 asynchronous jobs and credential-free WAV downloads. - Require a developer API key and Node.js 20.3 or newer. - Retrieve voices from the API; add quota and job-status tools. diff --git a/README.md b/README.md index 024c979..bdc0db1 100644 --- a/README.md +++ b/README.md @@ -40,11 +40,19 @@ HTTP is allowed only for loopback test servers. Audio downloads never include th | Tool | Arguments | Result | | --- | --- | --- | -| `flowspeech_tts` | Required `text`; optional `voice` (Kore), `output_path`, `request_id` | Local WAV path, job ID, request ID and usage | -| `flowspeech_tts_multi` | Required labelled `text`; optional `voice_a` (Charon), `voice_b` (Kore), `output_path`, `request_id` | Local WAV path and recovery IDs | +| `flowspeech_new_request_id` | None; no API key needed | Fresh UUID generated locally without network access | +| `flowspeech_tts` | Required `text` and `request_id`; optional `voice` (Kore), `output_path` | Local WAV path, job ID, request ID and usage | +| `flowspeech_tts_multi` | Required labelled `text` and `request_id`; optional `voice_a` (Charon), `voice_b` (Kore), `output_path` | Local WAV path and recovery IDs | | `flowspeech_list_voices` | Optional `gender`: male, female or all | Current authenticated voice catalog | | `flowspeech_quota` | None | Available, remaining and reserved credits | -| `flowspeech_get_job` | Required UUID `job_id` | Current job status and result | +| `flowspeech_get_job` | Exactly one UUID: `job_id` or `request_id` | Current job status and result; never creates work | + +Call `flowspeech_new_request_id` first and retain its `request_id` before invoking +either generation tool. Never use a fresh UUID merely because a call was interrupted. +All tools reject unknown fields and incorrect argument types at runtime. +Model, source, speed and format options are unsupported. Output paths are validated +and preflighted before paid submission; the final write still uses atomic +no-overwrite protection in case another process creates the file meanwhile. Two-speaker input uses one label per turn. Continuation lines belong to the preceding speaker: @@ -54,25 +62,69 @@ Speaker2: Thanks for inviting me. Speaker1: What should we cover first? ``` -Output is 24 kHz, mono, 16-bit WAV. Existing output files are never overwritten. Anyone holding a result URL can download it, so keep job results and recordings private when appropriate. +Output is 24 kHz, mono, 16-bit PCM WAV. The client validates all result fields +(`url`, `mimeType`, `sampleRate`, `channels`, `bitsPerSample`, `access`), +usage counters, UUID correlation, RIFF length, chunk boundaries and padding, +PCM format, and nonempty sample-aligned data before saving. Existing output files +are never overwritten. Anyone holding a result URL can download it, so keep job +results and recordings private when appropriate. ## Recovery and migration -Version 0.1.0 called the retired synchronous endpoint. Upgrade the npm package and restart your MCP client. All tools now require a developer key, including voice listing. The three original tool names remain available, and two read-only tools have been added. +Version 0.1.0 called the retired synchronous endpoint. Upgrade the npm package and +restart your MCP client. All API tools require a developer key, including voice +listing; only `flowspeech_new_request_id` is entirely local. All five existing +tool names remain available. -The server submits `{ "input": ... }` with a UUID idempotency key, polls no faster than five seconds, honors a longer `Retry-After`, and downloads `result.url`. It does not expect an API Base64 response. Transient API retries preserve the exact request ID and body, with at most five attempts per API request. +**Breaking change in 0.2.0:** both generation tools now require `request_id`; +automatic UUID creation inside a blocking generation call has been removed. +The TypeScript client's `generate(input, requestId, signal?)` likewise requires a +caller-known UUID. UUIDs are normalized to lowercase. The client rejects +responses whose request or job identity does not match the requested operation. -For deliberate recovery, supply a UUID `request_id` and reuse it with unchanged text and voices. Errors include available recovery IDs. A timeout or client cancellation stops local waiting; it does not cancel a server-side job. Use `flowspeech_get_job` to inspect it. A failed download or local save should be retried from the existing result rather than starting another recording. A terminal failed/cancelled job requires a new UUID only when intentionally requesting a new attempt. +The server submits `{ "input": ... }` with a UUID idempotency key, polls no faster +than five seconds (including status retries), honors a longer `Retry-After`, +and downloads `result.url`. A received cooldown still applies if reading the +response body fails. It does not expect an API Base64 response. Transient API +retries preserve the exact request ID and body, with at most five attempts per +API request. Redirects and size-validation failures are not retried. + +Recovery workflow: + +1. Call `flowspeech_new_request_id` and retain the returned UUID. +2. Pass that UUID as `request_id` to generation with the intended text and voices. +3. After a timeout or cancellation, call `flowspeech_get_job` with + `{"request_id":"YOUR_RETAINED_UUID"}`. If a job ID was already returned, + `{"job_id":"YOUR_JOB_UUID"}` is also supported. +4. While queued, running, merging or settling, wait at least five seconds between + status calls. On success, use the existing `result.url` for a credential-free + download. Do not request another recording to retry a download. +5. If lookup returns 404, retry the original generation with the same UUID and + unchanged text and voices. To retry local saving through MCP, replay that + same request with an unused output path; idempotency prevents new generation. + +Caller cancellation is passed to HTTP requests, response reads and polling waits. +It never sends a server-side cancellation request. MCP clients may time out +earlier than `FLOWSPEECH_TIMEOUT_MS` (the SDK default is 60 seconds); configure +their timeout as appropriate. Cancelled MCP requests may not receive a final +error response, which is why retaining the UUID **before submission** is required. +A deleted success result has no downloadable audio. A terminal failed/cancelled +job requires a new UUID only when intentionally requesting a new attempt. ## Development and tests ```sh npm ci --ignore-scripts npm test -npm pack --dry-run +npm run test:packed ``` -Tests cover mocked v1 contracts and a loopback HTTP server exercised through the built MCP stdio process. They do not call paid production generation. See [CHANGELOG.md](CHANGELOG.md) and the [public API documentation](https://flowspeech.io/docs/public-api). +Tests cover mocked v1 contracts, real WAV fixtures and a loopback HTTP server +exercised through the built MCP stdio process. Packed tests rebuild the tarball, +inspect its members and credentials patterns, compare packaged bytes with local +files, and rerun the client and stdio suites against the extracted package. +They never call paid production generation. Node 20 and 22 CI run both suites. +See [CHANGELOG.md](CHANGELOG.md) and the [public API documentation](https://flowspeech.io/docs/public-api). ## License diff --git a/SKILL.md b/SKILL.md index efd769d..fd22c53 100644 --- a/SKILL.md +++ b/SKILL.md @@ -40,17 +40,41 @@ For MCP clients, configure the server with stdio transport: } ``` -Node.js 20.3 or newer and a FlowSpeech developer API key are required. Set FLOWSPEECH_API_KEY in the private environment passed to the MCP process. Generation requires active paid API access and consumes account credits. Do not ask the user to paste secrets, account credentials, or private tokens into chat; use the MCP client's environment or secret manager. +Node.js 20.3 or newer and a FlowSpeech developer API key are required for API +operations. The local flowspeech_new_request_id tool needs no key or network. +Set FLOWSPEECH_API_KEY in the private environment passed to the MCP process. +Generation requires active paid API access and consumes account credits. +Do not ask the user to paste secrets, account credentials, or private tokens into +chat; use the MCP client's environment or secret manager. ## Workflow 1. Clarify the target format: single voice, two-speaker dialogue, or voice exploration. 2. If the user has not chosen a voice, use `flowspeech_list_voices` or pick a sensible default. -3. For single-speaker audio, call `flowspeech_tts` with the text and selected voice. -4. For two-speaker audio, call `flowspeech_tts_multi` with `Speaker1:` and `Speaker2:` labels. -5. Return the generated audio file path and briefly describe the voice choices used. +3. Call `flowspeech_new_request_id` and retain the returned `request_id` before submitting any text. +4. For single-speaker audio, call `flowspeech_tts` with that required `request_id`, text and selected voice. +5. For two-speaker audio, call `flowspeech_tts_multi` with that required `request_id` and `Speaker1:` / `Speaker2:` labels. +6. Return the generated audio file path and briefly describe the voice choices used. -The server uses API v1 job creation, polling and separate WAV download. It does not send credentials to the audio host. Use flowspeech_quota for available credits and flowspeech_get_job for an existing UUID job. On timeout, recover using the reported request/job ID instead of creating duplicate work. A request_id UUID can be supplied and reused only with identical text and voices. Local cancellation does not cancel the server job, and existing output files are not overwritten. +Version 0.2.0 requires a caller-known UUID on both generation tools; calls without +request_id are rejected before submission. Unknown fields, invalid argument +types and invalid output paths are rejected before paid work. Do not supply +unsupported model, source, speed or format options. + +The server uses API v1 job creation, polling and separate validated PCM WAV +download. It does not send credentials to the audio host. Use flowspeech_quota +for available credits. After timeout or cancellation, call flowspeech_get_job +with exactly one of request_id (the UUID retained before submission) or job_id. +Wait at least five seconds between status queries. If lookup returns 404, retry +the original generation with the same UUID and unchanged text/voices. If the job +succeeded, download its existing result URL without API credentials. To retry +saving through MCP, replay that unchanged request with an unused output path. +Never create a new UUID merely to retry an interrupted request or download. + +MCP cancellation can suppress the final error message, so do not rely on that +message to recover an automatically generated ID. Caller cancellation stops local +HTTP/poll/download work but never cancels the paid server job. Existing output +files are not overwritten. Deliberate new recordings require fresh UUIDs. ## Emotion And Pause Control diff --git a/VALIDATION.md b/VALIDATION.md new file mode 100644 index 0000000..919827c --- /dev/null +++ b/VALIDATION.md @@ -0,0 +1,62 @@ +# 0.2.0 hardening handoff (2026-10-26) + +Base: `7a40afe` on `codex/public-api-v1`. No commits, pushes, publishes, +production requests, real credentials, or Raycast edits were made. + +## Changes + +All six release-gate findings are addressed: + +1. Strict runtime allowed-field/type validation and output-path preflight run + before paid submission; atomic no-overwrite saves preserve recovery IDs. +2. Generation requires a caller-known UUID. The local + `flowspeech_new_request_id` tool needs neither network nor API key. + MCP cancellation reaches the HTTP client without cancelling the paid job. +3. Unsupported options are rejected rather than ignored. +4. Result metadata and usage are validated. WAV parsing checks RIFF bounds, + complete padded chunks, PCM format, and nonempty aligned audio data. +5. Normalized UUIDs are correlated on create, poll, lookup, and recovery. +6. Retry-After survives body-read failures. Status retries and polling wait + at least five seconds, bounded by one total deadline. + +Existing tool names remain available. Breaking 0.2.0 change: both generation +tools require `request_id`. The shared TypeScript client now requires +`generate(input, requestId, signal?)`; callers must retain the UUID before +calling it. `findJob(requestId, signal?)` supports recovery without submission. +The coordinator must adapt Raycast callers when copying the hardened client. + +## Verification + +Local runtimes: Node 20.19.5 and Node 22.14.0, npm 10.8.2 and 10.9.2. + +- `npm test`: 121 passed, 0 failed (109 client, 12 stdio), on each runtime. +- `npm run test:packed`: rebuilt TypeScript and tarball; the same 121 tests + passed against extracted packaged JavaScript, 0 failed, on each runtime. +- `git diff --check`: passed. +- Tarball: `mcp-flowspeech-server-0.2.0.tgz`, 14,097 bytes, nine allowlisted + members; each member matches its local source/build counterpart. +- SHA-256: `16961d6e2502e9ff3225d530ad366db1840cf8518f8fa13af0692e2dfd32af3e`. +- Packaged secret-pattern scan passed; no tests, caches, or credentials shipped. + +The fake HTTP tests bind loopback only and use fake credentials. The sandbox +initially blocked that bind; reruns with approved loopback access passed. +Packed tests reuse installed workspace dependencies, but import and launch only +the extracted implementation. Node 20/22 CI now runs both suites; these new +changes have not been pushed or run in remote CI. + +## Changed files + +`.github/workflows/test.yml`, `.gitignore`, `CHANGELOG.md`, `README.md`, +`SKILL.md`, `package.json`, `src/client.ts`, `src/index.ts`, +`test/client.test.mjs`, `test/stdio.test.mjs`, new `test/fixtures.mjs`, +new `scripts/test-packed.mjs`, and this report. Ignored `dist/` was rebuilt; +the existing untracked 0.2.0 tarball was replaced. Package version and lockfile +remain 0.2.0; dependencies were not changed. + +## Coordinator release steps + +Review the diff, run Node 20/22 CI, then commit/push from the coordinator. +Verify npm 0.2.0 is still unpublished before publishing this exact tarball with +the coordinator's authorized 2FA flow. Do not overwrite an existing release. +No implementation blocker remains from the six findings; publication and the +new remote CI run remain coordinator actions. diff --git a/package.json b/package.json index 9becca7..47cdaf1 100644 --- a/package.json +++ b/package.json @@ -34,9 +34,10 @@ "scripts": { "build": "tsc", "test": "npm run build && node --test test/*.test.mjs", + "test:packed": "npm run build && node scripts/test-packed.mjs", "dev": "tsc --watch", "start": "node dist/index.js", - "prepublishOnly": "npm test" + "prepublishOnly": "npm test && npm run test:packed" }, "dependencies": { "@modelcontextprotocol/sdk": "^1.12.0" diff --git a/scripts/test-packed.mjs b/scripts/test-packed.mjs new file mode 100644 index 0000000..ad32f0b --- /dev/null +++ b/scripts/test-packed.mjs @@ -0,0 +1,53 @@ +import assert from 'node:assert/strict'; +import { execFileSync, spawnSync } from 'node:child_process'; +import { createHash } from 'node:crypto'; +import { mkdir, mkdtemp, readFile, rm } from 'node:fs/promises'; +import { fileURLToPath } from 'node:url'; +import path from 'node:path'; + +const root = fileURLToPath(new URL('..', import.meta.url)); +const env = { ...process.env, npm_config_cache: path.join(root, '.npm-cache'), LC_ALL: 'C' }; +const npmCli = process.env.npm_execpath; +assert.ok(npmCli, 'Run this check through npm run test:packed'); +const packed = JSON.parse(execFileSync(process.execPath, [npmCli, 'pack', '--ignore-scripts', '--json'], { cwd: root, env, encoding: 'utf8' })); +assert.equal(packed.length, 1); +assert.equal(packed[0].version, '0.2.0'); +const archive = path.join(root, packed[0].filename); +const expected = [ + 'LICENSE', 'dist/client.js', 'dist/index.js', 'package.json', 'CHANGELOG.md', + 'README.md', 'SKILL.md', 'dist/client.d.ts', 'dist/index.d.ts', +].map(file => 'package/' + file).sort(); +const members = execFileSync('tar', ['-tzf', archive], { encoding: 'utf8', env }).trim().split('\n').sort(); +assert.deepEqual(members, expected, 'Unexpected archive files'); +const secretPattern = /(?:npm_[A-Za-z0-9]{30,}|gh[pousr]_[A-Za-z0-9]{30,}|pypi-[A-Za-z0-9_-]{30,}|-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----|(?:fs_live_|sk_live_)[A-Za-z0-9_-]{24,})/; +for (const name of members) { + const bytes = execFileSync('tar', ['-xOf', archive, name], { env }); + assert.ok(!secretPattern.test(bytes.toString()), 'Potential credential in ' + name); + assert.ok(!bytes.includes(Buffer.from('fake-test-key')), 'Test fixture leaked into package'); + const source = await readFile(path.join(root, name.slice('package/'.length))); + assert.deepEqual(bytes, source, 'Archive differs from reviewed local file: ' + name); +} +const scratch = path.join(root, '.test-tmp'); +await mkdir(scratch, { recursive: true }); +const directory = await mkdtemp(path.join(scratch, 'packed-')); +try { + execFileSync('tar', ['-xzf', archive, '-C', directory], { env }); + const target = path.join(directory, 'package'); + const manifest = JSON.parse(await readFile(path.join(target, 'package.json'), 'utf8')); + assert.equal(manifest.bin['mcp-flowspeech-server'], 'dist/index.js'); + assert.equal(manifest.version, '0.2.0'); + assert.ok((await readFile(path.join(target, manifest.bin['mcp-flowspeech-server']), 'utf8')).startsWith('#!/usr/bin/env node')); + // Dependencies resolve from the existing workspace install; implementation imports + // and the child stdio process both use only the extracted package's dist files. + const result = spawnSync(process.execPath, ['--test', 'test/client.test.mjs', 'test/stdio.test.mjs'], { + cwd: root, env: { ...env, FLOWSPEECH_TEST_PACKAGE: target }, stdio: 'inherit', + }); + assert.equal(result.status, 0, 'Packed client/stdio regression suite failed'); + console.log(JSON.stringify({ + archive: path.basename(archive), bytes: (await readFile(archive)).length, members: members.length, + sha256: createHash('sha256').update(await readFile(archive)).digest('hex'), + packedSourceMatches: true, secretScan: 'passed', + }, null, 2)); +} finally { + await rm(directory, { recursive: true, force: true }); +} diff --git a/src/client.ts b/src/client.ts index beb014f..373f167 100644 --- a/src/client.ts +++ b/src/client.ts @@ -1,17 +1,24 @@ -import { randomUUID } from 'node:crypto'; import { setTimeout as delay } from 'node:timers/promises'; export type SpeechInput = | { mode: 'single'; text: string; voiceName: string } | { mode: 'multi'; segments: { speaker: string; text: string; voiceName: string }[] }; +export interface AudioResult { + url: string; + mimeType: 'audio/wav'; + sampleRate: 24000; + channels: 1; + bitsPerSample: 16; + access: 'link'; +} export interface Job { id: string; - requestId?: string; + requestId: string; status: string; - result?: { url: string; mimeType: string } | null; + result?: AudioResult | null; resultDeleted?: boolean; - usage?: unknown; - error?: { code?: string }; + usage: { billableCharacters: number; reservedCredits: number; chargedCredits: number }; + error?: { code: string }; } export interface Voice { name: string; description: string; gender: string } interface Context { deadline: number; requestId?: string; jobId?: string; signal?: AbortSignal } @@ -29,47 +36,94 @@ const PENDING = new Set(['queued', 'running', 'merging', 'settling']); const TERMINAL = new Set(['success', 'failed', 'cancelled']); const TRANSIENT = new Set([429, 500, 502, 503, 504]); +class InvalidResponse extends Error {} function object(value: unknown): Record { - if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid API response'); + if (!value || typeof value !== 'object' || Array.isArray(value)) throw new InvalidResponse('Expected an object'); return value as Record; } -export function validateId(id: string): string { - if (!UUID.test(id)) throw new Error('Expected a UUID request or job ID'); - return id; +function nonempty(value: unknown, name: string, maximum = Infinity): string { + if (typeof value !== 'string' || !value.trim() || value.length > maximum) throw new Error(`Invalid ${name}`); + return value; +} +function fields(value: Record, allowed: string[]): void { + if (Object.keys(value).some(key => !allowed.includes(key))) throw new Error('Unsupported speech input fields'); +} +function counter(value: unknown): boolean { + return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0; +} +export function validateId(id: unknown): string { + if (typeof id !== 'string' || !UUID.test(id)) throw new Error('Expected a UUID request or job ID'); + return id.toLowerCase(); } function safeUrl(value: string, allowLocal: boolean): URL { + if (typeof value !== 'string' || /[\x00-\x20\\]/.test(value)) throw new InvalidResponse('Invalid URL'); const url = new URL(value); const local = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname); - if (url.username || url.password || url.hash || (url.protocol !== 'https:' && !(allowLocal && local && url.protocol === 'http:'))) throw new Error('Expected an HTTPS URL without embedded credentials'); + if (url.username || url.password || url.hash || (url.protocol !== 'https:' && !(allowLocal && local && url.protocol === 'http:'))) throw new InvalidResponse('Expected an HTTPS URL without embedded credentials'); return url; } -function retryDelay(headers: Headers, fallback: number): number { - const value = headers.get('retry-after'); +function retryDelay(headers: Headers | undefined, fallback: number): number { + const value = headers?.get('retry-after'); if (!value) return fallback; const seconds = /^\d+(?:\.\d+)?$/.test(value) ? Number(value) : (Date.parse(value) - Date.now()) / 1000; return Number.isFinite(seconds) ? Math.max(fallback, seconds * 1000) : fallback; } -async function boundedBody(response: Response, maximum: number): Promise { - if (Number(response.headers.get('content-length')) > maximum) { +async function boundedBody(response: Response, maximum: number, signal: AbortSignal): Promise { + const header = response.headers.get('content-length'); + if (header !== null && (!/^\d+$/.test(header) || !Number.isSafeInteger(Number(header)) || Number(header) > maximum)) { await response.body?.cancel(); - throw new Error('Response exceeds configured size limit'); + throw new InvalidResponse('Response exceeds configured size limit or has an invalid length'); } const reader = response.body?.getReader(); - if (!reader) throw new Error('Empty response body'); + if (!reader) throw new InvalidResponse('Empty response body'); + const abort = () => { void reader.cancel().catch(() => {}); }; + signal.addEventListener('abort', abort, { once: true }); const chunks: Uint8Array[] = []; let length = 0; try { for (;;) { + signal.throwIfAborted(); const part = await reader.read(); + signal.throwIfAborted(); if (part.done) break; length += part.value.length; - if (length > maximum) throw new Error('Response exceeds configured size limit'); + if (length > maximum) throw new InvalidResponse('Response exceeds configured size limit'); chunks.push(part.value); } - } finally { await reader.cancel().catch(() => {}); } + } finally { + signal.removeEventListener('abort', abort); + await reader.cancel().catch(() => {}); + } return Buffer.concat(chunks, length); } +function speechInput(value: unknown): SpeechInput { + const input = object(value); + let result: SpeechInput; + if (input.mode === 'single') { + fields(input, ['mode', 'text', 'voiceName']); + result = { mode: 'single', text: nonempty(input.text, 'speech text'), voiceName: nonempty(input.voiceName, 'voice name', 100) }; + } else if (input.mode === 'multi') { + fields(input, ['mode', 'segments']); + if (!Array.isArray(input.segments) || !input.segments.length || input.segments.length > 1000) throw new Error('Expected 1 to 1000 speaker turns'); + const assignments = new Map(); + result = { mode: 'multi', segments: input.segments.map(value => { + const turn = object(value); + fields(turn, ['speaker', 'text', 'voiceName']); + const speaker = nonempty(turn.speaker, 'speaker label', 100).trim(); + const voiceName = nonempty(turn.voiceName, 'voice name', 100).trim(); + const text = nonempty(turn.text, 'speech text'); + if (assignments.has(speaker) && assignments.get(speaker) !== voiceName) throw new Error('Each speaker must use one consistent voice'); + assignments.set(speaker, voiceName); + return { speaker, text, voiceName }; + }) }; + } else throw new Error('Expected single or multi speech mode'); + const turns = result.mode === 'single' ? [result] : result.segments; + if (turns.reduce((n, turn) => n + turn.text.length, 0) > 100_000) throw new Error('Speech exceeds 100000 UTF-16 code units'); + if (Buffer.byteLength(JSON.stringify({ input: result })) > 1024 * 1024) throw new Error('Input exceeds the JSON body limit'); + return result; +} export function dialogueInput(text: string, voiceA: string, voiceB: string): SpeechInput { + nonempty(text, 'dialogue'); const segments: { speaker: string; text: string; voiceName: string }[] = []; for (const line of text.split(/\r?\n/)) { const match = /^(Speaker[12]):\s*(.*)$/.exec(line.trim()); @@ -77,8 +131,34 @@ export function dialogueInput(text: string, voiceA: string, voiceB: string): Spe else if (line.trim() && segments.length) segments[segments.length - 1].text += '\n' + line; else if (line.trim()) throw new Error('Dialogue must start with Speaker1: or Speaker2:'); } - if (!segments.length || segments.some(segment => !segment.text.trim())) throw new Error('Every speaker turn needs spoken text'); - return { mode: 'multi', segments }; + return speechInput({ mode: 'multi', segments }); +} +export function validateWav(audio: Uint8Array): void { + const bytes = Buffer.from(audio.buffer, audio.byteOffset, audio.byteLength); + const invalid = () => new InvalidResponse('Downloaded result is not a complete 24000 Hz mono 16-bit PCM WAV'); + if (bytes.length < 12 || bytes.toString('latin1', 0, 4) !== 'RIFF' || bytes.toString('latin1', 8, 12) !== 'WAVE' || bytes.readUInt32LE(4) + 8 !== bytes.length) throw invalid(); + let offset = 12, formatSeen = false, dataSeen = false; + // RIFF chunks have independent lengths and an extra pad byte when their size is odd. + while (offset < bytes.length) { + if (bytes.length - offset < 8) throw invalid(); + const name = bytes.toString('latin1', offset, offset + 4); + const size = bytes.readUInt32LE(offset + 4); + const start = offset + 8, end = start + size, next = end + (size % 2); + if (next > bytes.length) throw invalid(); + if (name === 'fmt ') { + if (formatSeen || dataSeen || size < 16) throw invalid(); + if (size !== 16 && (size < 18 || bytes.readUInt16LE(start + 16) !== size - 18)) throw invalid(); + if (bytes.readUInt16LE(start) !== 1 || bytes.readUInt16LE(start + 2) !== 1 || + bytes.readUInt32LE(start + 4) !== 24000 || bytes.readUInt32LE(start + 8) !== 48000 || + bytes.readUInt16LE(start + 12) !== 2 || bytes.readUInt16LE(start + 14) !== 16) throw invalid(); + formatSeen = true; + } else if (name === 'data') { + if (!formatSeen || dataSeen || size === 0 || size % 2 !== 0) throw invalid(); + dataSeen = true; + } + offset = next; + } + if (!formatSeen || !dataSeen) throw invalid(); } export class FlowSpeechClient { @@ -89,7 +169,7 @@ export class FlowSpeechClient { private readonly now: () => number; private readonly sleep: (ms: number, signal?: AbortSignal) => Promise; constructor(private readonly options: Options) { - if (!options.apiKey?.trim() || /[\r\n]/.test(options.apiKey)) throw new Error('Set FLOWSPEECH_API_KEY to a developer API key'); + if (typeof options.apiKey !== 'string' || !options.apiKey || /[^\x21-\x7e]/.test(options.apiKey)) throw new Error('Set FLOWSPEECH_API_KEY to a developer API key without whitespace'); const base = safeUrl(options.baseUrl ?? 'https://flowspeech.io', true); if (base.pathname !== '/' || base.search) throw new Error('API base URL must be an origin without a path or query'); this.baseUrl = base.origin; @@ -115,38 +195,50 @@ export class FlowSpeechClient { await this.sleep(ms, context.signal); this.remaining(context); } + private signal(context: Context, requestLimit: number): AbortSignal { + const timeout = AbortSignal.timeout(Math.max(1, Math.ceil(Math.min(requestLimit, this.remaining(context))))); + return context.signal ? AbortSignal.any([timeout, context.signal]) : timeout; + } private async api(path: string, context: Context, body?: unknown): Promise<{ data: Record; headers: Headers }> { const encoded = body === undefined ? undefined : JSON.stringify(body); for (let attempt = 0; attempt < 5; attempt++) { this.remaining(context); - let response: Response; + let response: Response | undefined; let raw: Uint8Array; + const fallback = Math.max(body === undefined ? 5000 : 1000, 1000 * 2 ** attempt); try { - const timeout = AbortSignal.timeout(Math.max(1, Math.ceil(Math.min(30_000, this.remaining(context))))); + const signal = this.signal(context, 30_000); response = await this.fetcher(this.baseUrl + path, { - method: body === undefined ? 'GET' : 'POST', redirect: 'error', credentials: 'omit', - signal: context.signal ? AbortSignal.any([timeout, context.signal]) : timeout, + method: body === undefined ? 'GET' : 'POST', redirect: 'manual', credentials: 'omit', signal, headers: { Authorization: `Bearer ${this.options.apiKey}`, ...(encoded === undefined ? {} : { 'Content-Type': 'application/json', 'Idempotency-Key': context.requestId! }), }, body: encoded, }); - raw = await boundedBody(response, 1024 * 1024); - } catch { + if (response.status >= 300 && response.status < 400) { + await response.body?.cancel(); + throw new InvalidResponse('Unexpected API redirect refused'); + } + raw = await boundedBody(response, 1024 * 1024, signal); + } catch (error) { this.remaining(context); + if (error instanceof InvalidResponse) throw error; + if (response && !response.ok && !TRANSIENT.has(response.status)) throw new Error(`FlowSpeech HTTP ${response.status}: unreadable error response`); if (attempt === 4) throw new Error('API transport failed after bounded retries'); - await this.pause(1000 * 2 ** attempt, context); + // A received Retry-After still applies if reading that response's body fails. + await this.pause(retryDelay(response?.headers, fallback), context); continue; } + this.remaining(context); let data: Record | undefined; try { data = object(JSON.parse(new TextDecoder().decode(raw))); } catch { /* Error responses may not be JSON. */ } if (response.ok) { - if (!data) throw new Error('API returned invalid JSON'); + if (!data) throw new InvalidResponse('API returned invalid JSON'); return { data, headers: response.headers }; } const error = data?.error && typeof data.error === 'object' ? data.error as Record : {}; if (TRANSIENT.has(response.status) && error.retryable !== false && attempt < 4) { - await this.pause(retryDelay(response.headers, 1000 * 2 ** attempt), context); + await this.pause(retryDelay(response.headers, fallback), context); continue; } const code = typeof error.code === 'string' && /^[a-zA-Z0-9_]{1,100}$/.test(error.code) ? error.code : 'api_error'; @@ -154,47 +246,78 @@ export class FlowSpeechClient { } throw new Error('API retry budget exhausted'); } - private job(data: Record): Job { - if (typeof data.id !== 'string' || !UUID.test(data.id) || typeof data.status !== 'string' || (!PENDING.has(data.status) && !TERMINAL.has(data.status))) throw new Error('API returned an invalid job ID or status'); - return data as unknown as Job; + private job(data: Record, expected: { jobId?: string; requestId?: string }): Job { + const id = validateId(data.id), requestId = validateId(data.requestId); + if (expected.jobId && id !== expected.jobId) throw new InvalidResponse('Status response changed the job ID'); + if (expected.requestId && requestId !== expected.requestId) throw new InvalidResponse('Response changed the request ID'); + if (typeof data.status !== 'string' || (!PENDING.has(data.status) && !TERMINAL.has(data.status))) throw new InvalidResponse('API returned an invalid job status'); + const usage = object(data.usage); + if (!['billableCharacters', 'reservedCredits', 'chargedCredits'].every(key => counter(usage[key]))) throw new InvalidResponse('Invalid job usage'); + if (data.resultDeleted !== undefined && typeof data.resultDeleted !== 'boolean') throw new InvalidResponse('Invalid deleted-result flag'); + if (data.status === 'success') { + if (data.resultDeleted === true) { + if (data.result !== null) throw new InvalidResponse('Deleted job must have a null audio result'); + } else { + if (!data.result) throw new InvalidResponse('Completed job has no audio result'); + const result = object(data.result); + if (typeof result.url !== 'string' || result.mimeType !== 'audio/wav' || + result.sampleRate !== 24000 || result.channels !== 1 || result.bitsPerSample !== 16 || + result.access !== 'link') throw new InvalidResponse('Invalid audio result metadata'); + safeUrl(result.url, new URL(this.baseUrl).protocol === 'http:'); + } + } + if (data.error !== undefined) { + const error = object(data.error); + if (typeof error.code !== 'string' || !/^[a-zA-Z0-9_]{1,100}$/.test(error.code)) throw new InvalidResponse('Invalid job error code'); + } + return { ...data, id, requestId } as unknown as Job; } async quota(signal?: AbortSignal): Promise> { - return (await this.api('/api/v1/quota', this.context(signal))).data; + const data = (await this.api('/api/v1/quota', this.context(signal))).data; + const quota = object(data.quota); + if (!['total', 'remaining', 'reserved', 'available'].every(key => counter(quota[key]))) throw new InvalidResponse('Invalid quota response'); + return data; } async voices(signal?: AbortSignal): Promise { const data = (await this.api('/api/v1/voices', this.context(signal))).data; - if (!Array.isArray(data.voices) || data.voices.some(v => !v || typeof v.name !== 'string' || typeof v.description !== 'string' || typeof v.gender !== 'string')) throw new Error('Invalid voices response'); + if (!Array.isArray(data.voices) || data.voices.some(v => !v || typeof v.name !== 'string' || !v.name.trim() || typeof v.description !== 'string' || typeof v.gender !== 'string')) throw new InvalidResponse('Invalid voices response'); return data.voices as Voice[]; } async getJob(id: string, signal?: AbortSignal): Promise { - return this.job((await this.api(`/api/v1/tts/jobs/${validateId(id)}`, this.context(signal))).data); + const jobId = validateId(id); + return this.job((await this.api(`/api/v1/tts/jobs/${jobId}`, this.context(signal))).data, { jobId }); } - async generate(input: SpeechInput, requestId: string = randomUUID(), signal?: AbortSignal): Promise<{ job: Job; audio: Uint8Array; requestId: string }> { - validateId(requestId); + async findJob(id: string, signal?: AbortSignal): Promise { + const requestId = validateId(id); + return this.job((await this.api(`/api/v1/tts/jobs?requestId=${requestId}`, this.context(signal))).data, { requestId }); + } + async generate(input: SpeechInput, requestId: string, signal?: AbortSignal): Promise<{ job: Job; audio: Uint8Array; requestId: string }> { + requestId = validateId(requestId); const context = this.context(signal, requestId); try { - const turns = input.mode === 'single' ? [input] : input.segments; - if (!turns?.length || turns.length > 1000 || turns.some(t => !t.text?.trim() || !t.voiceName?.trim()) || turns.reduce((n, t) => n + t.text.length, 0) > 100_000) throw new Error('Invalid speech text, voice or input limits'); - if (Buffer.byteLength(JSON.stringify({ input })) > 1024 * 1024) throw new Error('Input exceeds the JSON body limit'); - let result = await this.api('/api/v1/tts/jobs', context, { input }); - let job = this.job(result.data); + const validated = speechInput(input); + let result = await this.api('/api/v1/tts/jobs', context, { input: validated }); + let job = this.job(result.data, { requestId }); context.jobId = job.id; while (PENDING.has(job.status)) { await this.pause(retryDelay(result.headers, 5000), context); - result = await this.api(`/api/v1/tts/jobs/${job.id}`, context); - job = this.job(result.data); - if (job.id !== context.jobId) throw new Error('Status response changed the job ID'); + result = await this.api(`/api/v1/tts/jobs/${context.jobId}`, context); + job = this.job(result.data, { jobId: context.jobId, requestId }); } - if (job.status !== 'success') throw new Error(`Generation ${job.status}`); - if (!job.result || typeof job.result.url !== 'string') throw new Error(job.resultDeleted ? 'Audio result was deleted' : 'Completed job has no audio result'); - if (job.result.mimeType !== 'audio/wav') throw new Error('Unexpected audio format; expected audio/wav'); - const url = safeUrl(job.result.url, new URL(this.baseUrl).protocol === 'http:'); - // Download independently, without API credentials or automatic redirects. - const timeout = AbortSignal.timeout(Math.max(1, Math.ceil(Math.min(120_000, this.remaining(context))))); - const audioResponse = await this.fetcher(url.toString(), { redirect: 'error', credentials: 'omit', signal: signal ? AbortSignal.any([timeout, signal]) : timeout }); - if (!audioResponse.ok) throw new Error(`Audio download HTTP ${audioResponse.status}; retry this download, not generation`); - const audio = await boundedBody(audioResponse, this.maxAudioBytes); - if (audio.length < 12 || Buffer.from(audio.subarray(0, 4)).toString() !== 'RIFF' || Buffer.from(audio.subarray(8, 12)).toString() !== 'WAVE') throw new Error('Downloaded result is not a WAV file'); + if (job.status !== 'success') throw new Error(`Generation ${job.status}${job.error ? ': ' + job.error.code : ''}`); + if (job.resultDeleted) throw new Error('Audio result was deleted'); + const url = safeUrl(job.result!.url, new URL(this.baseUrl).protocol === 'http:'); + // Downloads have no API credentials and never follow redirects. + const downloadSignal = this.signal(context, 120_000); + const audioResponse = await this.fetcher(url.toString(), { redirect: 'manual', credentials: 'omit', signal: downloadSignal }); + if (audioResponse.status !== 200) { + await audioResponse.body?.cancel(); + throw new Error(`Audio download HTTP ${audioResponse.status}; retry this download, not generation`); + } + const audio = await boundedBody(audioResponse, this.maxAudioBytes, downloadSignal); + this.remaining(context); + validateWav(audio); + this.remaining(context); return { job, audio, requestId }; } catch (error) { const message = error instanceof Error ? error.message : 'Operation failed'; diff --git a/src/index.ts b/src/index.ts index a9cd117..cf86a1c 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,22 +1,57 @@ #!/usr/bin/env node +import { randomUUID } from 'node:crypto'; import { Server } from '@modelcontextprotocol/sdk/server/index.js'; import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; import { CallToolRequestSchema, ListToolsRequestSchema, type Tool } from '@modelcontextprotocol/sdk/types.js'; -import { mkdir, writeFile } from 'node:fs/promises'; +import { access, lstat, mkdir, stat, writeFile } from 'node:fs/promises'; +import { constants } from 'node:fs'; import path from 'node:path'; import os from 'node:os'; -import { FlowSpeechClient, dialogueInput } from './client.js'; +import { FlowSpeechClient, dialogueInput, validateId } from './client.js'; const VERSION = '0.2.0'; -const outputDirectory = expandHome(process.env.FLOWSPEECH_OUTPUT_DIR || '~/.flowspeech-mcp/audio'); function expandHome(value: string): string { return value === '~' ? os.homedir() : value.startsWith('~/') ? path.join(os.homedir(), value.slice(2)) : path.resolve(value); } function stringArg(args: Record, key: string, fallback?: string): string { - const value = args[key] ?? fallback; + const value = args[key] === undefined ? fallback : args[key]; if (typeof value !== 'string' || !value.trim()) throw new Error(`${key} must be a nonempty string`); return value; } +function allowedFields(args: Record, allowed: string[]): void { + if (Object.keys(args).some(key => !allowed.includes(key))) throw new Error('Unsupported tool argument'); +} +function outputPath(value: string): string { + if (/[\x00-\x1f\x7f]/.test(value) || value.endsWith(path.sep)) throw new Error('output_path must name a file without control characters'); + const file = expandHome(value); + if (path.parse(file).root === file) throw new Error('output_path must name a file'); + return file; +} +async function checkDirectory(directory: string): Promise { + let current = directory; + for (;;) { + try { + const info = await stat(current); + if (!info.isDirectory()) throw new Error('Output parent must be a directory'); + await access(current, constants.W_OK); + return; + } catch (error) { + if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw new Error('Output parent is not a writable directory'); + const parent = path.dirname(current); + if (parent === current) throw new Error('Output parent is unavailable'); + current = parent; + } + } +} +async function checkFile(file: string): Promise { + let exists = true; + try { await lstat(file); } catch (error) { + if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw new Error('Cannot inspect output_path'); + exists = false; + } + if (exists) throw new Error('Cannot save audio without overwriting an existing file'); + await checkDirectory(path.dirname(file)); +} function client(): FlowSpeechClient { return new FlowSpeechClient({ apiKey: process.env.FLOWSPEECH_API_KEY || '', baseUrl: process.env.FLOWSPEECH_BASE_URL, @@ -25,21 +60,25 @@ function client(): FlowSpeechClient { } const outputProperties = { output_path: { type: 'string', description: 'Optional output WAV file path. An existing file is not overwritten.' }, - request_id: { type: 'string', description: 'Optional UUID for retrying the same text and voice without creating duplicate work.' }, + request_id: { type: 'string', format: 'uuid', description: 'Required caller-known UUID. Get one with flowspeech_new_request_id; reuse only for unchanged text and voices.' }, }; const tools: Tool[] = [ - { name: 'flowspeech_tts', description: 'Generate a WAV recording with FlowSpeech. Requires an API key and paid API access; consumes account credits.', inputSchema: { - type: 'object', properties: { text: { type: 'string' }, voice: { type: 'string', default: 'Kore' }, ...outputProperties }, required: ['text'], + { name: 'flowspeech_tts', description: 'Generate a WAV recording with FlowSpeech. Requires a caller-known request UUID, an API key and paid API access; consumes account credits.', inputSchema: { + type: 'object', additionalProperties: false, properties: { text: { type: 'string' }, voice: { type: 'string', default: 'Kore' }, ...outputProperties }, required: ['text', 'request_id'], } }, - { name: 'flowspeech_tts_multi', description: 'Generate a two-speaker WAV recording. Each turn starts with Speaker1: or Speaker2:. Consumes account credits.', inputSchema: { - type: 'object', properties: { text: { type: 'string' }, voice_a: { type: 'string', default: 'Charon' }, voice_b: { type: 'string', default: 'Kore' }, ...outputProperties }, required: ['text'], + { name: 'flowspeech_tts_multi', description: 'Generate a two-speaker WAV recording with a caller-known request UUID. Each turn starts with Speaker1: or Speaker2:. Consumes account credits.', inputSchema: { + type: 'object', additionalProperties: false, properties: { text: { type: 'string' }, voice_a: { type: 'string', default: 'Charon' }, voice_b: { type: 'string', default: 'Kore' }, ...outputProperties }, required: ['text', 'request_id'], } }, { name: 'flowspeech_list_voices', description: 'Retrieve the current voice catalog from FlowSpeech.', inputSchema: { - type: 'object', properties: { gender: { type: 'string', enum: ['male', 'female', 'all'], default: 'all' } }, + type: 'object', additionalProperties: false, properties: { gender: { type: 'string', enum: ['male', 'female', 'all'], default: 'all' } }, } }, - { name: 'flowspeech_quota', description: 'Read available, remaining and reserved API credits.', inputSchema: { type: 'object', properties: {} } }, - { name: 'flowspeech_get_job', description: 'Read an existing job by UUID without creating a new recording.', inputSchema: { - type: 'object', properties: { job_id: { type: 'string' } }, required: ['job_id'], + { name: 'flowspeech_quota', description: 'Read available, remaining and reserved API credits.', inputSchema: { type: 'object', additionalProperties: false, properties: {} } }, + { name: 'flowspeech_get_job', description: 'Read an existing job by job UUID or caller-known request UUID without creating a recording. Supply exactly one ID.', inputSchema: { + type: 'object', additionalProperties: false, properties: { job_id: { type: 'string', format: 'uuid' }, request_id: { type: 'string', format: 'uuid' } }, + oneOf: [{ required: ['job_id'] }, { required: ['request_id'] }], + } }, + { name: 'flowspeech_new_request_id', description: 'Generate a fresh request UUID locally, without network access or an API key. Keep it before starting one recording.', inputSchema: { + type: 'object', additionalProperties: false, properties: {}, } }, ]; const server = new Server({ name: 'flowspeech', version: VERSION }, { capabilities: { tools: {} } }); @@ -47,34 +86,52 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools })); server.setRequestHandler(CallToolRequestSchema, async (request, extra) => { const { name, arguments: args = {} } = request.params; try { - const api = client(); let text: string; - if (name === 'flowspeech_list_voices') { + if (name === 'flowspeech_new_request_id') { + allowedFields(args, []); + text = JSON.stringify({ request_id: randomUUID() }); + } else if (name === 'flowspeech_list_voices') { + allowedFields(args, ['gender']); const gender = stringArg(args, 'gender', 'all'); if (!['male', 'female', 'all'].includes(gender)) throw new Error('Invalid gender filter'); - text = JSON.stringify((await api.voices(extra.signal)).filter(v => gender === 'all' || v.gender === gender), null, 2); + text = JSON.stringify((await client().voices(extra.signal)).filter(v => gender === 'all' || v.gender === gender), null, 2); } else if (name === 'flowspeech_quota') { - text = JSON.stringify(await api.quota(extra.signal), null, 2); + allowedFields(args, []); + text = JSON.stringify(await client().quota(extra.signal), null, 2); } else if (name === 'flowspeech_get_job') { - text = JSON.stringify(await api.getJob(stringArg(args, 'job_id'), extra.signal), null, 2); + allowedFields(args, ['job_id', 'request_id']); + if (Number(args.job_id !== undefined) + Number(args.request_id !== undefined) !== 1) throw new Error('Supply exactly one of job_id or request_id'); + const byJob = args.job_id !== undefined; + const id = validateId(stringArg(args, byJob ? 'job_id' : 'request_id')); + const api = client(); + text = JSON.stringify(await (byJob ? api.getJob(id, extra.signal) : api.findJob(id, extra.signal)), null, 2); } else if (name === 'flowspeech_tts' || name === 'flowspeech_tts_multi') { + allowedFields(args, name === 'flowspeech_tts' + ? ['text', 'voice', 'output_path', 'request_id'] + : ['text', 'voice_a', 'voice_b', 'output_path', 'request_id']); + const requestId = validateId(stringArg(args, 'request_id')); const script = stringArg(args, 'text'); const input = name === 'flowspeech_tts' ? { mode: 'single' as const, text: script, voiceName: stringArg(args, 'voice', 'Kore') } : dialogueInput(script, stringArg(args, 'voice_a', 'Charon'), stringArg(args, 'voice_b', 'Kore')); - const requestId = args.request_id === undefined ? undefined : stringArg(args, 'request_id'); - const result = await api.generate(input, requestId, extra.signal); - const file = args.output_path === undefined - ? path.join(outputDirectory, `flowspeech-${result.job.id}.wav`) - : expandHome(stringArg(args, 'output_path')); + const customFile = args.output_path === undefined ? undefined : outputPath(stringArg(args, 'output_path')); + const directoryValue = process.env.FLOWSPEECH_OUTPUT_DIR || '~/.flowspeech-mcp/audio'; + if (/[\x00-\x1f\x7f]/.test(directoryValue)) throw new Error('Invalid output directory'); + const outputDirectory = expandHome(directoryValue); + if (customFile) await checkFile(customFile); + else await checkDirectory(outputDirectory); + const result = await client().generate(input, requestId, extra.signal); + const file = customFile ?? path.join(outputDirectory, `flowspeech-${result.job.id}.wav`); try { + extra.signal.throwIfAborted(); await mkdir(path.dirname(file), { recursive: true }); - await writeFile(file, result.audio, { flag: 'wx', mode: 0o600 }); + extra.signal.throwIfAborted(); + await writeFile(file, result.audio, { flag: 'wx', mode: 0o600, signal: extra.signal }); } catch { - throw new Error(`Cannot save audio without overwriting an existing file. Retrieve jobId=${result.job.id}; requestId=${result.requestId}. Do not create another recording.`); + throw new Error(`Cannot save audio without overwriting an existing file, or operation stopped. Retrieve jobId=${result.job.id}; requestId=${result.requestId}. Do not create another recording.`); } - text = `Audio saved to: ${file}\nFormat: audio/wav\nJob ID: ${result.job.id}\nRequest ID: ${result.requestId}\nUsage: ${JSON.stringify(result.job.usage ?? {})}`; - } else throw new Error(`Unknown tool: ${name}`); + text = `Audio saved to: ${file}\nFormat: audio/wav\nJob ID: ${result.job.id}\nRequest ID: ${result.requestId}\nUsage: ${JSON.stringify(result.job.usage)}`; + } else throw new Error('Unknown tool'); return { content: [{ type: 'text', text }] }; } catch (error) { return { isError: true, content: [{ type: 'text', text: error instanceof Error ? error.message : 'FlowSpeech operation failed' }] }; diff --git a/test/client.test.mjs b/test/client.test.mjs index 4611bcd..4392bde 100644 --- a/test/client.test.mjs +++ b/test/client.test.mjs @@ -1,91 +1,188 @@ import test from 'node:test'; import assert from 'node:assert/strict'; -import { FlowSpeechClient, dialogueInput } from '../dist/client.js'; +import { setTimeout as delay } from 'node:timers/promises'; +import { + FlowSpeechClient, dialogueInput, validateId, validateWav, id, requestId, input, + result, wav, job, json, brokenResponse, harness, chunk, riff, format, +} from './fixtures.mjs'; -const id = 'b698824b-de05-486d-8833-05d5c4522a39'; -const requestId = '51382b81-9d36-49a5-994e-9b67686c6bd1'; -const input = { mode: 'single', text: 'Hello', voiceName: 'Kore' }; -const wav = Buffer.from('RIFF\x24\x00\x00\x00WAVEfmt '); -const done = { id, status: 'success', result: { url: 'https://audio.example.test/result.wav', mimeType: 'audio/wav' } }; -const json = (body, status = 200, headers = {}) => new Response(JSON.stringify(body), { status, headers }); -function harness(steps, options = {}) { - const calls = [], sleeps = []; - let now = 0; - const client = new FlowSpeechClient({ apiKey: 'test-key', now: () => now, - sleep: async ms => { sleeps.push(ms); now += ms; }, - fetch: async (url, init) => { - calls.push({ url: String(url), init }); - const next = steps.shift(); - if (next instanceof Error) throw next; - assert.ok(next, 'unexpected request'); - return next; - }, ...options }); - return { client, calls, sleeps }; -} - -test('single create, queued polling, Retry-After and credential-free WAV download', async () => { - const h = harness([json({ id, status: 'queued' }, 202, { 'Retry-After': '8' }), json(done), new Response(wav)]); - const result = await h.client.generate(input, requestId); - assert.deepEqual(result.audio, wav); - assert.equal(result.requestId, requestId); - assert.deepEqual(h.sleeps, [8000]); +test('single creation, all pending states and credential-free audio', async () => { + const h = harness(['queued', 'running', 'merging', 'settling'].map(state => json(job(state), 202, { 'Retry-After': '8' })).concat([json(job()), new Response(wav)])); + const completed = await h.client.generate(input, requestId); + assert.deepEqual(completed.audio, wav); + assert.equal(completed.requestId, requestId); + assert.deepEqual(h.sleeps, [8000, 8000, 8000, 8000]); assert.equal(h.calls[0].url, 'https://flowspeech.io/api/v1/tts/jobs'); assert.deepEqual(JSON.parse(h.calls[0].init.body), { input }); - assert.equal(h.calls[0].init.headers.Authorization, 'Bearer test-key'); assert.equal(h.calls[0].init.headers['Idempotency-Key'], requestId); - assert.equal(h.calls[1].url, `https://flowspeech.io/api/v1/tts/jobs/${id}`); - assert.equal(h.calls[2].init.headers, undefined); - assert.ok(h.calls.every(c => c.init.redirect === 'error' && c.init.credentials === 'omit')); + for (const call of h.calls.slice(0, -1)) assert.equal(call.init.headers.Authorization, 'Bearer test-key'); + assert.equal(h.calls.at(-1).init.headers, undefined); + assert.ok(h.calls.every(call => call.init.redirect === 'manual' && call.init.credentials === 'omit')); }); -test('network retry preserves body and UUID', async () => { - const h = harness([new Error('network'), json(done), new Response(wav)]); +test('network retries preserve the exact body and UUID', async () => { + const h = harness([new Error('network'), json(job()), new Response(wav)]); await h.client.generate(input, requestId); assert.equal(h.calls[0].init.body, h.calls[1].init.body); assert.equal(h.calls[0].init.headers['Idempotency-Key'], h.calls[1].init.headers['Idempotency-Key']); assert.deepEqual(h.sleeps, [1000]); }); -test('429 respects Retry-After and reuses request ID', async () => { - const h = harness([json({ error: { code: 'rate_limited', retryable: true } }, 429, { 'Retry-After': '9' }), json(done), new Response(wav)]); +test('429 and retryable 503 honor Retry-After', async () => { + const h = harness([json({ error: { retryable: true } }, 429, { 'Retry-After': '9' }), + json({ error: { retryable: true } }, 503, { 'Retry-After': '12' }), json(job()), new Response(wav)]); await h.client.generate(input, requestId); - assert.deepEqual(h.sleeps, [9000]); - assert.equal(h.calls[0].init.body, h.calls[1].init.body); + assert.deepEqual(h.sleeps, [9000, 12000]); + assert.equal(new Set(h.calls.slice(0, 3).map(call => call.init.body)).size, 1); }); -test('HTTP-date Retry-After never polls earlier than five seconds', async () => { - const h = harness([json({ id, status: 'queued' }, 202, { 'Retry-After': new Date(Date.now() + 15000).toUTCString() }), json(done), new Response(wav)]); +test('HTTP-date Retry-After is honored', async () => { + const h = harness([json(job('queued'), 202, { 'Retry-After': new Date(Date.now() + 15000).toUTCString() }), json(job()), new Response(wav)]); await h.client.generate(input, requestId); assert.ok(h.sleeps[0] >= 13000); }); -test('multi input preserves turn order and continuation lines', async () => { +for (const status of [200, 429, 503]) test('body-read failure preserves Retry-After on HTTP ' + status, async () => { + const h = harness([brokenResponse(status, { 'Retry-After': '20' }), json(job()), new Response(wav)]); + await h.client.generate(input, requestId); + assert.deepEqual(h.sleeps, [20000]); + assert.equal(h.calls[0].init.body, h.calls[1].init.body); +}); +test('body-read failure honors a dated cooldown', async () => { + const h = harness([brokenResponse(429, { 'Retry-After': new Date(Date.now() + 15000).toUTCString() }), json(job()), new Response(wav)]); + await h.client.generate(input, requestId); + assert.ok(h.sleeps[0] >= 13000); +}); +for (const failed of [() => new Error('network'), () => brokenResponse(), () => json({ error: { retryable: true } }, 429, { 'Retry-After': '1' })]) { + test('every status retry waits at least five seconds: ' + failed.toString(), async () => { + const h = harness([json(job('queued'), 202), failed(), json(job()), new Response(wav)]); + await h.client.generate(input, requestId); + assert.deepEqual(h.sleeps, [5000, 5000]); + assert.equal(h.calls[2].at - h.calls[1].at, 5000); + }); +} +test('long required cooldown exceeds deadline without another request', async () => { + const h = harness([brokenResponse(429, { 'Retry-After': '20' })], { timeoutMs: 10000 }); + await assert.rejects(h.client.generate(input, requestId), /Required wait.*requestId=/); + assert.equal(h.calls.length, 1); + assert.deepEqual(h.sleeps, []); +}); +test('multi input preserves turn order and continuation text', async () => { const multi = dialogueInput('Speaker1: Hello\nMore text\nSpeaker2: Hi\nSpeaker1: Bye', 'Charon', 'Kore'); - assert.deepEqual(multi.segments.map(s => s.voiceName), ['Charon', 'Kore', 'Charon']); + assert.deepEqual(multi.segments.map(segment => segment.voiceName), ['Charon', 'Kore', 'Charon']); assert.equal(multi.segments[0].text, 'Hello\nMore text'); - const h = harness([json(done), new Response(wav)]); + const h = harness([json(job()), new Response(wav)]); await h.client.generate(multi, requestId); assert.deepEqual(JSON.parse(h.calls[0].init.body), { input: multi }); assert.throws(() => dialogueInput('unlabelled', 'Kore', 'Charon')); assert.throws(() => dialogueInput('Speaker1:', 'Kore', 'Charon')); }); -for (const status of ['failed', 'cancelled']) test(`${status} is not successful even with HTTP 200`, async () => { - const h = harness([json({ id, status })]); - await assert.rejects(h.client.generate(input, requestId), new RegExp(`Generation ${status}.*jobId=${id}`)); +for (const status of ['failed', 'cancelled']) test(status + ' is not success even with HTTP 200', async () => { + const h = harness([json(job(status, { error: { code: 'TTS_STOPPED' } }))]); + await assert.rejects(h.client.generate(input, requestId), new RegExp('Generation ' + status + ': TTS_STOPPED.*jobId=' + id)); assert.equal(h.calls.length, 1); }); -for (const [name, body] of [ - ['deleted', { ...done, result: null, resultDeleted: true }], - ['missing', { ...done, result: null }], - ['unknown status', { id, status: 'complete' }], - ['missing ID', { status: 'success' }], -]) test(`rejects ${name} result`, async () => { - const h = harness([json(body)]); +test('deleted success is readable but cannot generate audio', async () => { + const deleted = job('success', { result: null, resultDeleted: true }); + const h = harness([json(deleted), json(deleted)]); + assert.equal((await h.client.getJob(id)).resultDeleted, true); + await assert.rejects(h.client.generate(input, requestId), /deleted.*jobId=/); + assert.equal(h.calls.length, 2); +}); +for (const [name, patch] of [ + ['unknown status', { status: 'complete' }], ['missing ID', { id: undefined }], + ['invalid ID type', { id: 42 }], ['missing request ID', { requestId: undefined }], + ['null result', { result: null }], ['missing result', { result: undefined }], + ['inconsistent deletion', { resultDeleted: true }], ['invalid deletion flag', { resultDeleted: 'true' }], + ['missing usage', { usage: undefined }], ['empty usage', { usage: {} }], + ['negative usage', { usage: { billableCharacters: -1, reservedCredits: 0, chargedCredits: 0 } }], + ['invalid error', { error: { code: 'private text with spaces' } }], +]) test('rejects ' + name, async () => { + const h = harness([json(job('success', patch))]); await assert.rejects(h.client.generate(input, requestId)); assert.equal(h.calls.length, 1); }); -test('deadline stops before a required wait and retains recovery IDs', async () => { - const h = harness([json({ id, status: 'queued' }, 202)], { timeoutMs: 4000 }); - await assert.rejects(h.client.generate(input, requestId), new RegExp(`timeout.*requestId=${requestId}.*jobId=${id}`)); - assert.equal(h.calls.length, 1); +for (const key of ['url', 'mimeType', 'sampleRate', 'channels', 'bitsPerSample', 'access']) { + test('rejects missing result metadata ' + key, async () => { + const metadata = { ...result }; + delete metadata[key]; + const h = harness([json(job('success', { result: metadata }))]); + await assert.rejects(h.client.generate(input, requestId), /metadata/); + assert.equal(h.calls.length, 1); + }); +} +for (const [key, value] of [['mimeType', 'audio/mpeg'], ['sampleRate', 48000], ['channels', 2], + ['bitsPerSample', 8], ['access', 'private'], ['channels', true], ['sampleRate', '24000']]) { + test('rejects incorrect result metadata ' + key + '=' + value, async () => { + const h = harness([json(job('success', { result: { ...result, [key]: value } }))]); + await assert.rejects(h.client.generate(input, requestId), /metadata/); + assert.equal(h.calls.length, 1); + }); +} +test('validates getJob and request-lookup response identities', async () => { + const different = harness([json(job('success', { id: requestId }))]); + await assert.rejects(different.client.getJob(id), /changed the job ID/); + const wrongRequest = harness([json(job('success', { requestId: id }))]); + await assert.rejects(wrongRequest.client.findJob(requestId), /changed the request ID/); }); -test('nonretryable errors never resubmit, hide raw server messages and secrets', async () => { +test('creation and polls reject different request identities before download', async () => { + const create = harness([json(job('success', { requestId: id }))]); + await assert.rejects(create.client.generate(input, requestId), /changed the request ID/); + assert.equal(create.calls.length, 1); + const poll = harness([json(job('queued')), json(job('success', { requestId: id }))]); + await assert.rejects(poll.client.generate(input, requestId), /changed the request ID/); + assert.equal(poll.calls.length, 2); +}); +test('poll rejects changed job identity', async () => { + const h = harness([json(job('queued')), json(job('success', { id: requestId }))]); + await assert.rejects(h.client.generate(input, requestId), /changed the job ID/); +}); +test('normalizes uppercase request and job UUIDs across all operations', async () => { + const upper = job('success', { id: id.toUpperCase(), requestId: requestId.toUpperCase() }); + const h = harness([json(upper), new Response(wav), json(upper), json(upper)]); + const completed = await h.client.generate(input, requestId.toUpperCase()); + assert.equal(completed.requestId, requestId); + assert.equal(completed.job.id, id); + assert.equal(completed.job.requestId, requestId); + assert.equal(h.calls[0].init.headers['Idempotency-Key'], requestId); + assert.equal((await h.client.getJob(id.toUpperCase())).id, id); + assert.equal((await h.client.findJob(requestId.toUpperCase())).requestId, requestId); + assert.equal(h.calls[2].url, 'https://flowspeech.io/api/v1/tts/jobs/' + id); + assert.equal(h.calls[3].url, 'https://flowspeech.io/api/v1/tts/jobs?requestId=' + requestId); +}); +for (const bad of [undefined, null, 42, '', '../quota', 'not-a-uuid']) test('rejects invalid caller UUID ' + bad, async () => { + const h = harness([]); + await assert.rejects(h.client.generate(input, bad)); + await assert.rejects(h.client.getJob(bad)); + await assert.rejects(h.client.findJob(bad)); + assert.equal(h.calls.length, 0); +}); +for (const key of ['model', 'source', 'speed', 'format', 'speakers', 'originalText']) test('rejects obsolete input field ' + key, async () => { + const h = harness([]); + await assert.rejects(h.client.generate({ ...input, [key]: 'unsupported' }, requestId), /Unsupported/); + assert.equal(h.calls.length, 0); +}); +for (const invalid of [ + null, [], { ...input, mode: 'other' }, { ...input, text: 42 }, { ...input, text: ' ' }, + { ...input, voiceName: null }, { ...input, text: 'x'.repeat(100001) }, + { mode: 'multi', segments: [] }, { mode: 'multi', segments: [{ speaker: '', text: 'Hi', voiceName: 'Kore' }] }, + { mode: 'multi', segments: [{ speaker: 'A', text: 'Hi', voiceName: 'Kore', speed: 2 }] }, + { mode: 'multi', segments: [{ speaker: 'A', text: 'Hi', voiceName: 'Kore' }, { speaker: 'A', text: 'Hi', voiceName: 'Puck' }] }, +]) test('strict speech runtime validation: ' + JSON.stringify(invalid).slice(0, 90), async () => { + const h = harness([]); + await assert.rejects(h.client.generate(invalid, requestId)); + assert.equal(h.calls.length, 0); +}); +test('quota, voices and lookup use authenticated v1 reads', async () => { + const quota = { total: 20, remaining: 20, reserved: 5, available: 15 }; + const h = harness([json({ quota, subscription: null, limits: {} }), json({ voices: [{ name: 'Kore', gender: 'female', description: 'Firm' }] }), json(job())]); + assert.equal((await h.client.quota()).quota.available, 15); + assert.equal((await h.client.voices())[0].name, 'Kore'); + assert.equal((await h.client.getJob(id)).id, id); + assert.ok(h.calls.every(call => call.init.method === 'GET' && call.init.headers.Authorization === 'Bearer test-key')); +}); +test('malformed quota and voices fail', async () => { + const h = harness([json({}), json({ voices: [{}] })]); + await assert.rejects(h.client.quota()); + await assert.rejects(h.client.voices()); +}); +test('nonretryable errors omit raw server messages and credentials', async () => { const h = harness([json({ error: { code: 'subscription_required', retryable: false, message: 'test-key private script' } }, 503)]); await assert.rejects(h.client.generate(input, requestId), error => { assert.match(error.message, /HTTP 503: subscription_required/); @@ -94,42 +191,52 @@ test('nonretryable errors never resubmit, hide raw server messages and secrets', }); assert.equal(h.calls.length, 1); }); -test('download failures do not create another job', async () => { - const h = harness([json(done), new Response('unavailable', { status: 503 })]); - await assert.rejects(h.client.generate(input, requestId), /retry this download, not generation/); - assert.equal(h.calls.length, 2); +test('nonretryable unreadable HTTP errors do not resubmit', async () => { + const h = harness([brokenResponse(401, { 'Retry-After': '20' })]); + await assert.rejects(h.client.generate(input, requestId), /HTTP 401/); + assert.equal(h.calls.length, 1); }); -test('bounded download rejects oversized and non-WAV payloads', async () => { - const h = harness([json(done), new Response(wav)], { maxAudioBytes: 8 }); - await assert.rejects(h.client.generate(input, requestId), /size limit/); - const bad = harness([json(done), new Response('not an audio file')]); - await assert.rejects(bad.client.generate(input, requestId), /not a WAV/); -}); -test('rejects insecure or credential-bearing result URLs before sending a request', async () => { - for (const url of ['http://example.com/a.wav', 'https://user:password@example.com/a.wav', 'file:///tmp/audio.wav']) { - const h = harness([json({ ...done, result: { ...done.result, url } })]); +test('invalid JSON, redirects and oversized API bodies never retry', async () => { + for (const response of [new Response('not JSON'), new Response('', { status: 302, headers: { Location: 'https://other.test' } }), + new Response('too big', { headers: { 'Content-Length': '1048577' } })]) { + const h = harness([response]); await assert.rejects(h.client.generate(input, requestId)); assert.equal(h.calls.length, 1); } }); -test('quota, voices and job lookup use authenticated v1 reads', async () => { - const h = harness([json({ quota: { available: 15 } }), json({ voices: [{ name: 'Kore', gender: 'female', description: 'Firm' }] }), json(done)]); - assert.equal((await h.client.quota()).quota.available, 15); - assert.equal((await h.client.voices())[0].name, 'Kore'); - assert.equal((await h.client.getJob(id)).id, id); - assert.deepEqual(h.calls.map(c => new URL(c.url).pathname), ['/api/v1/quota', '/api/v1/voices', `/api/v1/tts/jobs/${id}`]); - assert.ok(h.calls.every(c => c.init.method === 'GET' && c.init.headers.Authorization === 'Bearer test-key')); +test('download failures and redirects never create another job', async () => { + for (const status of [302, 503]) { + const h = harness([json(job()), new Response('', { status, headers: { Location: 'https://other.test' } })]); + await assert.rejects(h.client.generate(input, requestId), /retry this download, not generation/); + assert.equal(h.calls.length, 2); + assert.equal(h.calls[1].init.headers, undefined); + } }); -test('invalid configuration, UUID and input fail without requests', async () => { - assert.throws(() => new FlowSpeechClient({ apiKey: '' })); - assert.throws(() => new FlowSpeechClient({ apiKey: 'key', baseUrl: 'https://user:pass@example.com' })); - const h = harness([]); - await assert.rejects(h.client.getJob('../quota')); - await assert.rejects(h.client.generate(input, 'bad-id')); - await assert.rejects(h.client.generate({ ...input, text: ' ' }, requestId)); - assert.equal(h.calls.length, 0); +test('download size limit is enforced both with and without content length', async () => { + for (const response of [new Response(wav, { headers: { 'Content-Length': String(wav.length) } }), new Response(wav)]) { + const h = harness([json(job()), response], { maxAudioBytes: 8 }); + await assert.rejects(h.client.generate(input, requestId), /size limit/); + } }); -test('aborted operations never start generation', async () => { +for (const url of ['http://example.com/a.wav', 'https://user:password@example.com/a.wav', 'file:///tmp/audio.wav', 'https://audio.test/a#fragment', 'https://audio.test/\nrecording']) { + test('unsafe audio URL rejected before download: ' + url, async () => { + const h = harness([json(job('success', { result: { ...result, url } }))]); + await assert.rejects(h.client.generate(input, requestId)); + assert.equal(h.calls.length, 1); + }); +} +test('invalid configuration fails locally', () => { + for (const options of [{ apiKey: '' }, { apiKey: 'bad key' }, { apiKey: 'key', timeoutMs: NaN }, { apiKey: 'key', baseUrl: 'https://user:pass@example.com' }]) { + assert.throws(() => new FlowSpeechClient(options)); + } + assert.equal(validateId(requestId.toUpperCase()), requestId); +}); +test('deadline ends before a required poll with both recovery IDs', async () => { + const h = harness([json(job('queued'), 202)], { timeoutMs: 4000 }); + await assert.rejects(h.client.generate(input, requestId), new RegExp('timeout.*requestId=' + requestId + '.*jobId=' + id)); + assert.equal(h.calls.length, 1); +}); +test('pre-aborted operations do not submit', async () => { const h = harness([]); await assert.rejects(h.client.generate(input, requestId, AbortSignal.abort()), /stopped/); assert.equal(h.calls.length, 0); @@ -139,9 +246,55 @@ test('retry exhaustion is bounded', async () => { await assert.rejects(h.client.generate(input, requestId), /bounded retries/); assert.equal(h.calls.length, 5); }); -test('invalid JSON and changed job IDs are rejected', async () => { - const h = harness([new Response('not JSON')]); - await assert.rejects(h.client.generate(input, requestId), /invalid JSON/); - const changed = harness([json({ id, status: 'queued' }, 202), json({ ...done, id: requestId })]); - await assert.rejects(changed.client.generate(input, requestId), /changed the job ID/); +for (const useDeadline of [false, true]) test('audio stream ' + (useDeadline ? 'deadline' : 'cancellation') + ' stops reads and keeps IDs', { timeout: 2000 }, async () => { + const controller = new AbortController(); + let cancelled = false; + const stream = new ReadableStream({ cancel() { cancelled = true; } }); + const hold = setTimeout(() => {}, 1500); + const h = harness([json(job()), new Response(stream)], { timeoutMs: useDeadline ? 30 : 1000, now: () => performance.now() }); + const pending = h.client.generate(input, requestId, controller.signal); + if (!useDeadline) { await delay(10); controller.abort(); } + try { + await assert.rejects(pending, error => error.message.includes('requestId=' + requestId) && error.message.includes('jobId=' + id)); + assert.ok(cancelled); + assert.equal(h.calls.length, 2); + } finally { clearTimeout(hold); } +}); + +test('real WAV and odd padded ancillary chunks are accepted', () => { + validateWav(wav); + validateWav(riff([chunk('JUNK', Buffer.from([1])), chunk('fmt ', format()), chunk('data', Buffer.alloc(2)), chunk('LIST', Buffer.from([1, 2, 3]))])); + validateWav(riff([chunk('fmt ', Buffer.concat([format(), Buffer.alloc(2)])), chunk('data', Buffer.alloc(2))])); +}); +const invalidWavs = [ + ['header only', Buffer.from('RIFF\x04\0\0\0WAVE')], + ['truncated data', wav.subarray(0, -1)], ['trailing garbage', Buffer.concat([wav, Buffer.from([0])])], + ['missing fmt', riff([chunk('data', Buffer.alloc(2))])], ['missing data', riff([chunk('fmt ', format())])], + ['data before fmt', riff([chunk('data', Buffer.alloc(2)), chunk('fmt ', format())])], + ['empty data', riff([chunk('fmt ', format()), chunk('data', Buffer.alloc(0))])], + ['unaligned data', riff([chunk('fmt ', format()), chunk('data', Buffer.alloc(3))])], + ['duplicate data', riff([chunk('fmt ', format()), chunk('data', Buffer.alloc(2)), chunk('data', Buffer.alloc(2))])], + ['duplicate fmt', riff([chunk('fmt ', format()), chunk('fmt ', format()), chunk('data', Buffer.alloc(2))])], + ['short fmt', riff([chunk('fmt ', format().subarray(0, 14)), chunk('data', Buffer.alloc(2))])], + ['short extension', riff([chunk('fmt ', Buffer.concat([format(), Buffer.alloc(1)])), chunk('data', Buffer.alloc(2))])], + ['incomplete chunk header', riff([chunk('fmt ', format()), Buffer.from('data')])], +]; +for (const [offset, value, width, label] of [[0, 3, 2, 'float encoding'], [2, 2, 2, 'stereo'], [4, 48000, 4, 'sample rate'], + [8, 96000, 4, 'byte rate'], [12, 4, 2, 'alignment'], [14, 8, 2, 'bit depth']]) { + const fmt = format(); + if (width === 2) fmt.writeUInt16LE(value, offset); else fmt.writeUInt32LE(value, offset); + invalidWavs.push([label, riff([chunk('fmt ', fmt), chunk('data', Buffer.alloc(4))])]); +} +const oversizedChunk = Buffer.from(wav); oversizedChunk.writeUInt32LE(0xffffffff, 40); +invalidWavs.push(['oversized chunk', oversizedChunk]); +const highBitMagic = Buffer.from(wav); highBitMagic[0] |= 0x80; +invalidWavs.push(['non-ASCII RIFF magic', highBitMagic]); +const missingPadding = riff([chunk('fmt ', format()), chunk('data', Buffer.alloc(2)), chunk('JUNK', Buffer.alloc(1))]).subarray(0, -1); +missingPadding.writeUInt32LE(missingPadding.length - 8, 4); +invalidWavs.push(['missing padding', missingPadding]); +for (const [name, bytes] of invalidWavs) test('rejects malformed WAV: ' + name, async () => { + assert.throws(() => validateWav(bytes), /PCM WAV/); + const h = harness([json(job()), new Response(bytes)]); + await assert.rejects(h.client.generate(input, requestId), /PCM WAV.*jobId=/); + assert.equal(h.calls.length, 2); }); diff --git a/test/fixtures.mjs b/test/fixtures.mjs new file mode 100644 index 0000000..2c9f683 --- /dev/null +++ b/test/fixtures.mjs @@ -0,0 +1,68 @@ +import path from 'node:path'; +import { fileURLToPath, pathToFileURL } from 'node:url'; + +export const packageRoot = process.env.FLOWSPEECH_TEST_PACKAGE || fileURLToPath(new URL('..', import.meta.url)); +export const { FlowSpeechClient, dialogueInput, validateId, validateWav } = + await import(pathToFileURL(path.join(packageRoot, 'dist/client.js')).href); +export const id = 'b698824b-de05-486d-8833-05d5c4522a39'; +export const requestId = '51382b81-9d36-49a5-994e-9b67686c6bd1'; +export const input = { mode: 'single', text: 'Hello', voiceName: 'Kore' }; +export const audioUrl = 'https://audio.example.test/result.wav'; +export const result = { url: audioUrl, mimeType: 'audio/wav', sampleRate: 24000, channels: 1, bitsPerSample: 16, access: 'link' }; + +export function chunk(name, content) { + const bytes = Buffer.alloc(8 + content.length + content.length % 2); + bytes.write(name, 0, 4, 'ascii'); + bytes.writeUInt32LE(content.length, 4); + content.copy(bytes, 8); + return bytes; +} +export function riff(chunks) { + const body = Buffer.concat(chunks); + const header = Buffer.alloc(12); + header.write('RIFF'); + header.writeUInt32LE(body.length + 4, 4); + header.write('WAVE', 8); + return Buffer.concat([header, body]); +} +export function format() { + const bytes = Buffer.alloc(16); + bytes.writeUInt16LE(1, 0); + bytes.writeUInt16LE(1, 2); + bytes.writeUInt32LE(24000, 4); + bytes.writeUInt32LE(48000, 8); + bytes.writeUInt16LE(2, 12); + bytes.writeUInt16LE(16, 14); + return bytes; +} +export const wav = riff([chunk('fmt ', format()), chunk('data', Buffer.alloc(48))]); +export function job(status = 'success', extra = {}) { + return { + id, requestId, status, progress: { completed: status === 'success' ? 1 : 0, total: 1 }, + createdAt: '2026-10-26T00:00:00.000Z', updatedAt: '2026-10-26T00:00:01.000Z', + deadlineAt: '2026-10-26T02:00:00.000Z', + usage: { billableCharacters: 5, reservedCredits: status === 'queued' ? 5 : 0, chargedCredits: status === 'success' ? 5 : 0 }, + ...(status === 'success' ? { result: { ...result }, resultDeleted: false } : {}), + ...extra, + }; +} +export const json = (body, status = 200, headers = {}) => new Response(JSON.stringify(body), { status, headers }); +export function brokenResponse(status = 200, headers = {}) { + return new Response(new ReadableStream({ start(controller) { controller.error(new Error('interrupted body')); } }), { status, headers }); +} +export function harness(steps, options = {}) { + const calls = [], sleeps = []; + let now = 0; + const client = new FlowSpeechClient({ + apiKey: 'test-key', now: () => now, + sleep: async ms => { sleeps.push(ms); now += ms; }, + fetch: async (url, init) => { + calls.push({ url: String(url), init, at: now }); + const next = steps.shift(); + if (next instanceof Error) throw next; + if (!next) throw new Error('Unexpected fake request'); + return typeof next === 'function' ? next(url, init) : next; + }, ...options, + }); + return { client, calls, sleeps }; +} diff --git a/test/stdio.test.mjs b/test/stdio.test.mjs index 73c74eb..5fac71e 100644 --- a/test/stdio.test.mjs +++ b/test/stdio.test.mjs @@ -1,51 +1,219 @@ import test from 'node:test'; import assert from 'node:assert/strict'; import { createServer } from 'node:http'; -import { once } from 'node:events'; -import { mkdtemp, readFile, rm } from 'node:fs/promises'; -import { tmpdir } from 'node:os'; +import { once, EventEmitter } from 'node:events'; +import { mkdtemp, readFile, rm, mkdir, writeFile, readdir, stat } from 'node:fs/promises'; +import { setTimeout as delay } from 'node:timers/promises'; +import { fileURLToPath } from 'node:url'; import path from 'node:path'; import { Client } from '@modelcontextprotocol/sdk/client/index.js'; import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'; +import { id, requestId, wav, job, packageRoot } from './fixtures.mjs'; -test('built stdio server submits v1, saves WAV and refuses overwrites', async () => { - const directory = await mkdtemp(path.join(tmpdir(), 'flowspeech-mcp-test-')); - const id = 'b698824b-de05-486d-8833-05d5c4522a39'; - const requestId = '51382b81-9d36-49a5-994e-9b67686c6bd1'; - const wav = Buffer.from('RIFF\x24\0\0\0WAVEfmt '); - const requests = []; +const workspace = fileURLToPath(new URL('..', import.meta.url)); +async function setup(t, { queued = false, noKey = false, audio = wav, onCreate } = {}) { + const scratch = path.join(workspace, '.test-tmp'); + await mkdir(scratch, { recursive: true }); + const directory = await mkdtemp(path.join(scratch, 'stdio-')); + const requests = [], jobs = new Map(), events = new EventEmitter(); + let baseUrl; const server = createServer(async (req, res) => { - requests.push({ path: req.url, auth: req.headers.authorization }); - if (req.url === '/audio.wav') { res.end(wav); return; } - assert.equal(req.headers.authorization, 'Bearer fake-test-key'); - res.setHeader('Content-Type', 'application/json'); - if (req.url === '/api/v1/voices') { res.end(JSON.stringify({ voices: [{ name: 'Kore', gender: 'female', description: 'Firm' }] })); return; } - if (req.url !== '/api/v1/tts/jobs') { res.writeHead(404).end('{}'); return; } - assert.equal(req.headers['idempotency-key'], requestId); - let body = ''; for await (const chunk of req) body += chunk; - assert.deepEqual(JSON.parse(body), { input: { mode: 'single', text: 'Hello', voiceName: 'Kore' } }); - res.writeHead(202).end(JSON.stringify({ id, status: 'success', result: { url: `http://127.0.0.1:${server.address().port}/audio.wav`, mimeType: 'audio/wav' } })); + try { + let body = ''; + for await (const chunk of req) body += chunk; + requests.push({ path: req.url, method: req.method, auth: req.headers.authorization, key: req.headers['idempotency-key'], body }); + if (req.url === '/audio.wav') { res.end(audio); return; } + assert.equal(req.headers.authorization, 'Bearer fake-test-key'); + res.setHeader('Content-Type', 'application/json'); + if (req.url === '/api/v1/voices') { + res.end(JSON.stringify({ voices: [{ name: 'Kore', gender: 'female', description: 'Firm' }] })); return; + } + if (req.url === '/api/v1/quota') { + res.end(JSON.stringify({ quota: { total: 20, remaining: 20, reserved: 0, available: 20 }, subscription: null, limits: {} })); return; + } + if (req.url === '/api/v1/tts/jobs' && req.method === 'POST') { + const key = req.headers['idempotency-key']; + assert.match(key, /^[0-9a-f-]{36}$/); + const response = job(queued ? 'queued' : 'success', { + requestId: key, + ...(queued ? {} : { result: { ...job().result, url: baseUrl + '/audio.wav' } }), + }); + jobs.set(key, response); + await onCreate?.(JSON.parse(body), directory); + res.writeHead(202).end(JSON.stringify(response)); + events.emit('accepted'); + return; + } + if (req.url.startsWith('/api/v1/tts/jobs?requestId=')) { + const response = jobs.get(new URL(req.url, baseUrl).searchParams.get('requestId')); + res.writeHead(response ? 200 : 404).end(JSON.stringify(response || { error: { code: 'job_not_found', retryable: false } })); + return; + } + if (req.url === '/api/v1/tts/jobs/' + id) { + const response = [...jobs.values()][0] || job(); + res.end(JSON.stringify(response)); return; + } + res.writeHead(404).end(JSON.stringify({ error: { code: 'unexpected_route', retryable: false } })); + } catch (error) { + res.writeHead(500).end(JSON.stringify({ error: { code: 'fixture_error', retryable: false } })); + events.emit('fixtureError', error); + } }); - server.listen(0, '127.0.0.1'); await once(server, 'listening'); + const fixtureErrors = []; + events.on('fixtureError', error => fixtureErrors.push(error)); + server.listen(0, '127.0.0.1'); + await once(server, 'listening'); + baseUrl = 'http://127.0.0.1:' + server.address().port; const client = new Client({ name: 'test', version: '1.0.0' }); - try { - await client.connect(new StdioClientTransport({ command: process.execPath, args: ['dist/index.js'], env: { - ...process.env, FLOWSPEECH_API_KEY: 'fake-test-key', FLOWSPEECH_BASE_URL: `http://127.0.0.1:${server.address().port}`, FLOWSPEECH_OUTPUT_DIR: directory, - } })); - assert.equal((await client.listTools()).tools.length, 5); - const voices = await client.callTool({ name: 'flowspeech_list_voices', arguments: { gender: 'female' } }); - assert.match(voices.content[0].text, /Kore/); - const args = { name: 'flowspeech_tts', arguments: { text: 'Hello', request_id: requestId } }; - const result = await client.callTool(args); - assert.ok(!result.isError, JSON.stringify(result)); - assert.deepEqual(await readFile(path.join(directory, `flowspeech-${id}.wav`)), wav); - const repeat = await client.callTool(args); - assert.equal(repeat.isError, true); - assert.match(repeat.content[0].text, /without overwriting/); - assert.ok(requests.filter(r => r.path === '/audio.wav').every(r => r.auth === undefined)); - assert.ok(requests.every(r => !r.path.includes('/api/ai/'))); - } finally { - await client.close(); server.closeAllConnections(); await new Promise(resolve => server.close(resolve)); + t.after(async () => { + await client.close(); + server.closeAllConnections(); + await new Promise(resolve => server.close(resolve)); await rm(directory, { recursive: true, force: true }); + assert.deepEqual(fixtureErrors, []); + }); + await client.connect(new StdioClientTransport({ + command: process.execPath, args: [path.join(packageRoot, 'dist/index.js')], + env: { FLOWSPEECH_API_KEY: noKey ? '' : 'fake-test-key', FLOWSPEECH_BASE_URL: baseUrl, FLOWSPEECH_OUTPUT_DIR: directory }, + })); + return { client, directory, requests, jobs, events, baseUrl }; +} +const call = (client, name, args = {}, options) => client.callTool({ name, arguments: args }, undefined, options); +const content = response => response.content[0].text; + +test('six strict tool schemas retain the existing names and require generation UUIDs', async t => { + const { client } = await setup(t); + const tools = (await client.listTools()).tools; + assert.deepEqual(tools.map(tool => tool.name), [ + 'flowspeech_tts', 'flowspeech_tts_multi', 'flowspeech_list_voices', 'flowspeech_quota', 'flowspeech_get_job', 'flowspeech_new_request_id', + ]); + for (const tool of tools) assert.equal(tool.inputSchema.additionalProperties, false); + for (const name of ['flowspeech_tts', 'flowspeech_tts_multi']) { + assert.deepEqual(tools.find(tool => tool.name === name).inputSchema.required, ['text', 'request_id']); } }); +test('fresh caller UUIDs are local and require no API key', async t => { + const { client, requests } = await setup(t, { noKey: true }); + const first = await call(client, 'flowspeech_new_request_id'); + const second = await call(client, 'flowspeech_new_request_id'); + assert.ok(!first.isError && !second.isError); + const a = JSON.parse(content(first)).request_id, b = JSON.parse(content(second)).request_id; + assert.match(a, /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/); + assert.notEqual(a, b); + assert.deepEqual(requests, []); +}); +test('single stdio generation saves a valid private WAV and preserves recovery identity', async t => { + const { client, directory, requests } = await setup(t); + const generated = JSON.parse(content(await call(client, 'flowspeech_new_request_id'))).request_id; + const response = await call(client, 'flowspeech_tts', { text: 'Hello', request_id: generated.toUpperCase() }); + assert.ok(!response.isError, content(response)); + assert.match(content(response), new RegExp('Request ID: ' + generated)); + const filename = path.join(directory, 'flowspeech-' + id + '.wav'); + assert.deepEqual(await readFile(filename), wav); + assert.equal((await stat(filename)).mode & 0o777, 0o600); + const created = requests.find(request => request.method === 'POST'); + assert.equal(created.key, generated); + assert.deepEqual(JSON.parse(created.body), { input: { mode: 'single', text: 'Hello', voiceName: 'Kore' } }); + assert.ok(requests.filter(request => request.path === '/audio.wav').every(request => request.auth === undefined)); + const byRequest = await call(client, 'flowspeech_get_job', { request_id: generated.toUpperCase() }); + const byJob = await call(client, 'flowspeech_get_job', { job_id: id.toUpperCase() }); + assert.equal(JSON.parse(content(byRequest)).id, id); + assert.equal(JSON.parse(content(byJob)).requestId, generated); + assert.equal(requests.filter(request => request.method === 'POST').length, 1); +}); +test('multi stdio generation maps labelled speaker turns', async t => { + const { client, requests } = await setup(t); + const response = await call(client, 'flowspeech_tts_multi', { text: 'Speaker1: Hello\nSpeaker2: Hi', request_id: requestId }); + assert.ok(!response.isError, content(response)); + assert.deepEqual(JSON.parse(requests.find(request => request.method === 'POST').body), { input: { mode: 'multi', segments: [ + { speaker: 'Speaker1', text: 'Hello', voiceName: 'Charon' }, { speaker: 'Speaker2', text: 'Hi', voiceName: 'Kore' }, + ] } }); +}); +test('all invalid generation argument types and unsupported fields fail before network', async t => { + const { client, directory, requests } = await setup(t); + const invalid = [ + { text: 'Hello' }, { text: 'Hello', request_id: null }, { text: 'Hello', request_id: 42 }, + { text: 42, request_id: requestId }, { text: ' ', request_id: requestId }, + { text: 'Hello', request_id: requestId, voice: null }, { text: 'Hello', request_id: requestId, voice: 42 }, + ...[42, null, [], {}, '', ' ', 'bad\0file.wav', directory + path.sep].map(output_path => ({ text: 'Hello', request_id: requestId, output_path })), + ...['model', 'source', 'speed', 'format', 'originalText', 'speakers', 'voice_a'].map(key => ({ text: 'Hello', request_id: requestId, [key]: 'unsupported' })), + ]; + for (const args of invalid) { + const response = await call(client, 'flowspeech_tts', args); + assert.equal(response.isError, true, JSON.stringify(args)); + } + for (const args of [ + { text: 'Speaker1: Hi' }, { text: 'Speaker1: Hi', request_id: requestId, voice_a: null }, + { text: 'Speaker1: Hi', request_id: requestId, voice_b: [] }, + { text: 'Speaker1: Hi', request_id: requestId, output_path: 42 }, + { text: 'Speaker1: Hi', request_id: requestId, speed: 2 }, + ]) assert.equal((await call(client, 'flowspeech_tts_multi', args)).isError, true); + assert.deepEqual(requests, []); + assert.deepEqual(await readdir(directory), []); +}); +test('existing file and non-directory parent fail before submission', async t => { + const { client, directory, requests } = await setup(t); + const existing = path.join(directory, 'existing.wav'); + await writeFile(existing, 'preserve'); + for (const output_path of [existing, path.join(existing, 'nested.wav')]) { + assert.equal((await call(client, 'flowspeech_tts', { text: 'Hello', request_id: requestId, output_path })).isError, true); + } + assert.deepEqual(requests, []); + assert.equal(await readFile(existing, 'utf8'), 'preserve'); +}); +test('atomic no-overwrite failure after submission retains both IDs', async t => { + const { client, directory, requests } = await setup(t, { onCreate: async (_, dir) => { + await writeFile(path.join(dir, 'race.wav'), 'preserve'); + } }); + const response = await call(client, 'flowspeech_tts', { text: 'Hello', request_id: requestId, output_path: path.join(directory, 'race.wav') }); + assert.equal(response.isError, true); + assert.match(content(response), /without overwriting/); + assert.match(content(response), new RegExp('jobId=' + id)); + assert.match(content(response), new RegExp('requestId=' + requestId)); + assert.equal(await readFile(path.join(directory, 'race.wav'), 'utf8'), 'preserve'); + assert.equal(requests.filter(request => request.method === 'POST').length, 1); +}); +test('header-only WAV is not saved by stdio', async t => { + const { client, directory, requests } = await setup(t, { audio: Buffer.from('RIFF\x04\0\0\0WAVE') }); + const response = await call(client, 'flowspeech_tts', { text: 'Hello', request_id: requestId }); + assert.equal(response.isError, true); + assert.match(content(response), /PCM WAV/); + assert.deepEqual(await readdir(directory), []); + assert.equal(requests.filter(request => request.method === 'POST').length, 1); +}); +test('read-only tools and UUID tool reject unknown arguments before network', async t => { + const { client, requests } = await setup(t); + for (const [name, args] of [ + ['flowspeech_new_request_id', { text: 'no' }], ['flowspeech_quota', { request_id: requestId }], + ['flowspeech_list_voices', { gender: null }], ['flowspeech_list_voices', { gender: 'other' }], + ['flowspeech_list_voices', { unknown: true }], ['flowspeech_get_job', {}], + ['flowspeech_get_job', { job_id: id, request_id: requestId }], ['flowspeech_get_job', { job_id: 42 }], + ['flowspeech_get_job', { request_id: null }], ['flowspeech_get_job', { job_id: id, extra: 1 }], + ]) assert.equal((await call(client, name, args)).isError, true, name); + assert.deepEqual(requests, []); +}); +test('quota and voices remain available over stdio', async t => { + const { client } = await setup(t); + assert.equal(JSON.parse(content(await call(client, 'flowspeech_quota'))).quota.available, 20); + assert.equal(JSON.parse(content(await call(client, 'flowspeech_list_voices', { gender: 'female' })))[0].name, 'Kore'); +}); +for (const cancellation of ['signal', 'caller timeout']) test(cancellation + ' preserves caller-known recovery without submitting again', { timeout: 5000 }, async t => { + const { client, directory, requests, events } = await setup(t, { queued: true }); + const knownId = JSON.parse(content(await call(client, 'flowspeech_new_request_id'))).request_id; + const accepted = once(events, 'accepted'); + const controller = new AbortController(); + const pending = call(client, 'flowspeech_tts', { text: 'Hello', request_id: knownId }, { + signal: controller.signal, timeout: cancellation === 'caller timeout' ? 300 : 2000, + }).then(value => ({ value }), error => ({ error })); + await accepted; + if (cancellation === 'signal') controller.abort(); + assert.ok((await pending).error); + await delay(20); + const recovered = await call(client, 'flowspeech_get_job', { request_id: knownId }); + assert.ok(!recovered.isError, content(recovered)); + assert.equal(JSON.parse(content(recovered)).requestId, knownId); + assert.equal(JSON.parse(content(recovered)).status, 'queued'); + assert.equal(requests.filter(request => request.method === 'POST').length, 1); + assert.ok(requests.every(request => !request.path.endsWith('/cancel'))); + assert.deepEqual(await readdir(directory), []); +});