diff --git a/package-lock.json b/package-lock.json index 61ad694..372fc5b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@withone/cli", - "version": "2.16.1", + "version": "2.16.2", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@withone/cli", - "version": "2.16.1", + "version": "2.16.2", "dependencies": { "@clack/prompts": "^0.9.1", "commander": "^13.1.0", diff --git a/package.json b/package.json index d2b5fed..18043fe 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@withone/cli", - "version": "2.16.1", + "version": "2.16.2", "description": "CLI for managing One", "type": "module", "files": [ diff --git a/skills/one/references/flows.md b/skills/one/references/flows.md index ddb3dc9..5f14465 100644 --- a/skills/one/references/flows.md +++ b/skills/one/references/flows.md @@ -290,7 +290,7 @@ The `if`, `unless`, `condition.expression`, `while.condition`, `transform.expres ## Step Types -Every step needs `id`, `name` and `type`, plus the config object for its type. Common optional fields on any step: `if` / `unless` (JS conditions), `onError`, `timeoutMs` (the step fails with `status: "timeout"` and `errorCode: "TIMEOUT"`; the underlying API call or command is not cancelled), `requires` and `outputSchema` (below). +Every step needs `id`, `name` and `type`, plus the config object for its type. Common optional fields on any step: `if` / `unless` (JS conditions), `onError`, `timeoutMs` (the step fails with `status: "timeout"` and `errorCode: "TIMEOUT"`; an `action` or `paginate` step aborts its request, but any other step type keeps running in the background, including the steps inside a timed-out `loop`, `parallel`, `while` or `flow` step), `requires` and `outputSchema` (below). ### `action` — Execute a One API action @@ -690,6 +690,8 @@ Scoped per-flow: a sub-flow uses its own `defaultOnError`, not the parent's. Match rules: number entries are compared against any 3-digit token in the error message (covers `HTTP 429`, `status 502`, etc.); string entries match `error.errorCode` exactly OR appear as a case-insensitive substring of the message (covers Node error codes like `ETIMEDOUT` and our own `TIMEOUT`). +For an `action` or `paginate` step with `timeoutMs`, the CLI aborts its local preflight and request on timeout, and a `paginate` step fetches no further pages. A configured retry follows the existing `retryDelayMs` and backoff policy; the earlier operation may still be active when the retry begins, especially with `retryDelayMs: 0`. Aborting locally does not guarantee a remote write was rolled back: a write cancelled mid-request may or may not have reached the destination. Use the destination's idempotency support for stronger protection against duplicate writes. + **Inspecting retry outcomes.** A step that succeeded after retrying carries `$.steps..retries`, the number of retries it took (absent when the first attempt succeeded). A `retry` step that runs out of retries fails the flow, so it never lands as `status: "failed"`. `$.steps..error` is set on steps that failed under `continue` or `fallback`. A successful-after-retry step also emits a `step:retry-success` event with the retry count, so you can distinguish a clean first-attempt success from a recovered one in logs. diff --git a/src/lib/action-details.test.ts b/src/lib/action-details.test.ts index d48d0be..f1d92ae 100644 --- a/src/lib/action-details.test.ts +++ b/src/lib/action-details.test.ts @@ -129,6 +129,20 @@ describe('resolveActionDetails', () => { assert.deepEqual(result.details, FULL_DETAILS); }); + it('does not serve stale action details after preflight is aborted', async () => { + writeEntry(makeEntry(FULL_DETAILS, { ageSeconds: 7200, ttl: 3600 })); + const controller = new AbortController(); + const api = { + getActionDetailsWithMeta: async (_id: string, _etag?: string, signal?: AbortSignal) => + new Promise((_resolve, reject) => { + signal?.addEventListener('abort', () => reject(signal.reason), { once: true }); + }), + }; + const pending = resolveActionDetails(api, ACTION_ID, { signal: controller.signal }); + controller.abort(new Error('cancelled')); + await assert.rejects(pending, /cancelled/); + }); + it('routes the stale-fallback warning to a custom warn sink instead of stderr', async () => { writeEntry(makeEntry(FULL_DETAILS, { ageSeconds: 7200, ttl: 3600 })); const api = stubApi(() => { throw new Error('network down'); }); diff --git a/src/lib/action-details.ts b/src/lib/action-details.ts index 74895ab..26991d6 100644 --- a/src/lib/action-details.ts +++ b/src/lib/action-details.ts @@ -57,8 +57,9 @@ export function isActionDetailsEntry( export async function resolveActionDetails( api: Pick, actionId: string, - opts: { useCache?: boolean; warn?: (msg: string) => void } = {} + opts: { useCache?: boolean; warn?: (msg: string) => void; signal?: AbortSignal } = {} ): Promise { + opts.signal?.throwIfAborted(); const useCache = opts.useCache !== false; // Default warning sink is stderr; callers that resolve many actions (e.g. // `execute --parallel`) pass a deduping sink so a shared stale action only @@ -73,7 +74,8 @@ export async function resolveActionDetails( } try { - const result = await api.getActionDetailsWithMeta(actionId, cached?.etag ?? undefined); + const result = await api.getActionDetailsWithMeta(actionId, cached?.etag ?? undefined, opts.signal); + opts.signal?.throwIfAborted(); if (result.status === 304 && cached) { cached.cachedAt = new Date().toISOString(); @@ -85,6 +87,9 @@ export async function resolveActionDetails( writeCache(cachePath, entry); return { details: result.data, cacheHit: false, stale: false, entry }; } catch (fetchError) { + // Cancellation must not turn into a stale-cache fallback. In particular, + // an aborted preflight must never proceed to a write action. + opts.signal?.throwIfAborted(); if (cached) { warn( `Warning: serving cached action details (network unavailable, cached ${formatAge(getAge(cached))} ago)\n` diff --git a/src/lib/api-redirect.test.ts b/src/lib/api-redirect.test.ts index 35d7308..4951ba6 100644 --- a/src/lib/api-redirect.test.ts +++ b/src/lib/api-redirect.test.ts @@ -30,6 +30,26 @@ async function close(server: http.Server): Promise { await new Promise((resolve, reject) => server.close(error => error ? reject(error) : resolve())); } +/** + * Fails after `ms` instead of waiting forever. The abort tests wait on a real + * request; if the signal ever stops reaching fetch they must fail and still + * close their server. A test-level timeout is not enough: the timed-out body + * never reaches its finally block, so the open server keeps the run alive. + */ +async function bounded(promise: Promise, what: string, ms = 5_000): Promise { + let timer: NodeJS.Timeout | undefined; + try { + return await Promise.race([ + promise, + new Promise((_, reject) => { + timer = setTimeout(() => reject(new Error(`${what} did not happen within ${ms}ms`)), ms); + }), + ]); + } finally { + if (timer) clearTimeout(timer); + } +} + async function readRequest(req: IncomingMessage): Promise { let body = ''; for await (const chunk of req) body += chunk.toString(); @@ -106,6 +126,108 @@ describe('OneApi redirect credentials', () => { } }); + it('preserves an action request signal across a same-origin redirect', async (t) => { + const controller = new AbortController(); + const signals: (AbortSignal | null | undefined)[] = []; + t.mock.method(globalThis, 'fetch', async (_url: string | URL | Request, init?: RequestInit) => { + signals.push(init?.signal); + return signals.length === 1 + ? new Response(null, { status: 307, headers: { Location: '/v1/passthrough/moved' } }) + : new Response('{"ok":true}', { status: 200, headers: { 'content-type': 'application/json' } }); + }); + const api = new OneApi(SECRET, 'https://api.example.test/v1', {}); + await api.executePassthroughRequest({ + platform: 'test', actionId: action._id, connectionKey: CONNECTION, + signal: controller.signal, + }, action); + assert.deepEqual(signals, [controller.signal, controller.signal]); + }); + + it('aborts an in-flight passthrough fetch on a local server', async () => { + let received!: () => void; + const entered = new Promise(resolve => { received = resolve; }); + const server = await listen((_req, _res) => { received(); }); + try { + const controller = new AbortController(); + const api = new OneApi(SECRET, `${origin(server)}/v1`, {}); + const pending = api.executePassthroughRequest({ + platform: 'test', actionId: action._id, connectionKey: CONNECTION, + signal: controller.signal, + }, action); + await bounded(entered, 'the request reaching the server'); + controller.abort(); + await bounded(assert.rejects(pending), 'the aborted request rejecting'); + } finally { + await close(server); + } + }); + + it('does not call fetch when cancellation precedes passthrough dispatch', async (t) => { + let fetches = 0; + t.mock.method(globalThis, 'fetch', async () => { + fetches++; + return new Response('{}'); + }); + const controller = new AbortController(); + controller.abort(); + const api = new OneApi(SECRET, 'https://api.example.test/v1', {}); + await assert.rejects(api.executePassthroughRequest({ + platform: 'test', actionId: action._id, connectionKey: CONNECTION, + signal: controller.signal, + }, action)); + assert.equal(fetches, 0); + }); + + it('aborts while reading a passthrough response body', async (t) => { + let readingStarted!: () => void; + const reading = new Promise(resolve => { readingStarted = resolve; }); + const server = await listen((_req, res) => { + res.writeHead(200, { 'content-type': 'application/json' }); + res.write('{"incomplete":'); + res.flushHeaders(); + }); + try { + const nativeFetch = globalThis.fetch; + t.mock.method(globalThis, 'fetch', async (url: string | URL | Request, init?: RequestInit) => { + const response = await nativeFetch(url, init); + const read = response.text.bind(response); + response.text = () => { + readingStarted(); + return read(); + }; + return response; + }); + const controller = new AbortController(); + const api = new OneApi(SECRET, `${origin(server)}/v1`, {}); + const pending = api.executePassthroughRequest({ + platform: 'test', actionId: action._id, connectionKey: CONNECTION, + signal: controller.signal, + }, action); + await bounded(reading, 'the response body read starting'); + controller.abort(); + await bounded(assert.rejects(pending), 'the aborted body read rejecting'); + } finally { + await close(server); + } + }); + + it('does not follow a redirect if the signal was aborted while closing the first response', async (t) => { + const controller = new AbortController(); + let fetches = 0; + t.mock.method(globalThis, 'fetch', async () => { + fetches++; + return new Response(new ReadableStream({ cancel: () => controller.abort() }), { + status: 307, headers: { Location: '/v1/passthrough/moved' }, + }); + }); + const api = new OneApi(SECRET, 'https://api.example.test/v1', {}); + await assert.rejects(api.executePassthroughRequest({ + platform: 'test', actionId: action._id, connectionKey: CONNECTION, + signal: controller.signal, + }, action)); + assert.equal(fetches, 1); + }); + it('resolves relative redirects against the current URL', async () => { const paths: string[] = []; const server = await listen((req, res) => { diff --git a/src/lib/api.ts b/src/lib/api.ts index d81a8e3..4b0d274 100644 --- a/src/lib/api.ts +++ b/src/lib/api.ts @@ -93,6 +93,9 @@ async function fetchApi(url: string, init: RequestInit): Promise { let currentUrl = url; let request = { ...init, redirect: 'manual' as const }; for (let redirects = 0; ; redirects++) { + // The same signal is carried through same-origin redirects. A cancellation + // during response cleanup must not dispatch the next request. + request.signal?.throwIfAborted(); const response = await fetch(currentUrl, request); if (![301, 302, 303, 307, 308].includes(response.status)) return response; const location = response.headers.get('location'); @@ -149,8 +152,8 @@ export class OneApi { this.apiBase = apiBase ?? 'https://api.withone.ai/v1'; } - private async request(path: string): Promise { - return this.requestFull({ path }); + private async request(path: string, signal?: AbortSignal): Promise { + return this.requestFull({ path, signal }); } private async requestFull(opts: { @@ -159,6 +162,7 @@ export class OneApi { body?: unknown; headers?: Record; queryParams?: Record; + signal?: AbortSignal; }): Promise { let url = `${this.apiBase}${opts.path}`; if (opts.queryParams && Object.keys(opts.queryParams).length > 0) { @@ -175,6 +179,7 @@ export class OneApi { const fetchOpts: RequestInit = { method: opts.method || 'GET', headers, + signal: opts.signal, }; if (opts.body !== undefined) { @@ -223,13 +228,13 @@ export class OneApi { } } - async listConnections(): Promise { + async listConnections(signal?: AbortSignal): Promise { const allConnections: Connection[] = []; let page = 1; let totalPages = 1; do { - const response = await this.request(`/vault/connections?page=${page}&limit=100`); + const response = await this.request(`/vault/connections?page=${page}&limit=100`, signal); allConnections.push(...(response.rows || [])); totalPages = response.pages || 1; page++; @@ -391,10 +396,11 @@ export class OneApi { return Array.isArray(response) ? response : []; } - async getActionDetails(actionId: string): Promise { + async getActionDetails(actionId: string, signal?: AbortSignal): Promise { const response = await this.requestFull<{ rows: ActionDetails[] }>({ path: '/knowledge', queryParams: { _id: actionId }, + signal, }); const actions = response?.rows || []; @@ -412,6 +418,7 @@ export class OneApi { headers?: Record; queryParams?: Record; ifNoneMatch?: string; + signal?: AbortSignal; }): Promise> { let url = `${this.apiBase}${opts.path}`; if (opts.queryParams && Object.keys(opts.queryParams).length > 0) { @@ -432,6 +439,7 @@ export class OneApi { const fetchOpts: RequestInit = { method: opts.method || 'GET', headers, + signal: opts.signal, }; if (opts.body !== undefined) { @@ -463,12 +471,14 @@ export class OneApi { */ async getActionDetailsWithMeta( actionId: string, - ifNoneMatch?: string + ifNoneMatch?: string, + signal?: AbortSignal, ): Promise> { const result = await this.requestWithMeta<{ rows: ActionDetails[] }>({ path: '/knowledge', queryParams: { _id: actionId }, ifNoneMatch, + signal, }); if (result.status === 304) { @@ -487,7 +497,7 @@ export class OneApi { args: ExecuteActionArgs, preloadedAction?: ActionDetails ): Promise { - const action = preloadedAction ?? await this.getActionDetails(args.actionId); + const action = preloadedAction ?? await this.getActionDetails(args.actionId, args.signal); const method = action.method; const contentType = args.isFormData @@ -571,6 +581,7 @@ export class OneApi { const fetchOpts: RequestInit = { method, headers: requestHeaders, + signal: args.signal, }; if (method?.toLowerCase() !== 'get' && requestData !== undefined) { @@ -627,6 +638,7 @@ export class OneApi { }; } + args.signal?.throwIfAborted(); const response = await fetchApi(fullUrl, fetchOpts); if (!response.ok) { diff --git a/src/lib/flow-action-timeout.test.ts b/src/lib/flow-action-timeout.test.ts new file mode 100644 index 0000000..a493cf7 --- /dev/null +++ b/src/lib/flow-action-timeout.test.ts @@ -0,0 +1,340 @@ +import { after, before, describe, it } from 'node:test'; +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import os from 'node:os'; +import path from 'node:path'; +import { executeSingleStep } from './flow-engine.js'; +import type { OneApi } from './api.js'; +import type { FlowContext, FlowStep, FlowStepErrorConfig } from './flow-types.js'; +import type { ActionDetails } from './types.js'; +import { setHomeTo, snapshotHomeEnv, restoreHomeEnv, type HomeEnvSnapshot } from '../test-support/home.js'; + +let originalHome: HomeEnvSnapshot; +let temporaryHome: string; +let nextId = 0; + +before(() => { + originalHome = snapshotHomeEnv(); + temporaryHome = fs.mkdtempSync(path.join(os.tmpdir(), 'one-flow-timeout-')); + setHomeTo(temporaryHome); +}); + +after(() => { + restoreHomeEnv(originalHome); + fs.rmSync(temporaryHome, { recursive: true, force: true }); +}); + +function deferred() { + let resolve!: (value: T) => void; + let reject!: (error: Error) => void; + const promise = new Promise((yes, no) => { resolve = yes; reject = no; }); + return { promise, resolve, reject }; +} + +const nextTurn = () => new Promise(resolve => setImmediate(resolve)); +const context = (): FlowContext => ({ input: {}, env: {}, steps: {}, loop: {} }); + +async function bounded(promise: Promise, ms: number): Promise { + let timer: NodeJS.Timeout | undefined; + try { + return await Promise.race([ + promise, + new Promise((_, reject) => { + timer = setTimeout(() => reject(new Error('timeout handling waited indefinitely')), ms); + }), + ]); + } finally { + if (timer) clearTimeout(timer); + } +} + +function setup(overrides: { + details?: (signal?: AbortSignal) => Promise; + execute?: (signal?: AbortSignal) => Promise<{ responseData: unknown }>; +}, onError: FlowStep['onError'] = { strategy: 'continue' }) { + const actionId = `timeout-test-${++nextId}`; + const details = { _id: actionId, title: 'Test', method: 'POST', path: '/items', tags: [] } as ActionDetails; + const step: FlowStep = { + id: 'write', name: 'Write', type: 'action', timeoutMs: 75, onError, + action: { platform: 'test', actionId, connectionKey: 'test-connection' }, + }; + const api = { + getActionDetailsWithMeta: async (_id: string, _etag?: string, signal?: AbortSignal) => ({ + data: overrides.details ? await overrides.details(signal) : details, + status: 200, etag: null, + }), + executePassthroughRequest: async (args: { signal?: AbortSignal }) => + overrides.execute ? overrides.execute(args.signal) : { responseData: { ok: true } }, + } as unknown as OneApi; + return { step, api, details }; +} + +describe('flow action timeout cancellation', () => { + it('aborts the in-flight action and preserves TIMEOUT status', async () => { + let signal: AbortSignal | undefined; + const { step, api } = setup({ execute: async received => { + signal = received; + return new Promise((_resolve, reject) => received?.addEventListener('abort', () => reject(received.reason), { once: true })); + } }); + const result = await executeSingleStep(step, context(), api, 'admin', ['*'], { skipValidation: true }); + assert.equal(result.status, 'timeout'); + assert.equal(result.errorCode, 'TIMEOUT'); + assert.equal(signal?.aborted, true); + }); + + it('does not dispatch a write when preflight completes after timeout', async () => { + const preflight = deferred(); + let dispatched = 0; + const { step, api, details } = setup({ + details: () => preflight.promise, + execute: async () => { dispatched++; return { responseData: {} }; }, + }); + const result = await executeSingleStep(step, context(), api, 'admin', ['*'], { skipValidation: true }); + assert.equal(result.status, 'timeout'); + preflight.resolve(details); + await nextTurn(); + assert.equal(dispatched, 0); + }); + + it('lets a cooperative request settle during the configured retry delay', async () => { + const cleanup = deferred(); + const aborted = deferred(); + let calls = 0; + let active = false; + let retryEvents = 0; + const { step, api } = setup({ execute: async signal => { + calls++; + if (calls > 1) { + assert.equal(active, false, 'retry overlapped the previous request'); + return { responseData: { ok: true } }; + } + active = true; + return new Promise((_resolve, reject) => signal?.addEventListener('abort', () => { + aborted.resolve(); + void cleanup.promise.then(() => { active = false; reject(signal.reason); }); + }, { once: true })); + } }, { strategy: 'retry', retries: 1, retryDelayMs: 40 }); + const running = executeSingleStep(step, context(), api, 'admin', ['*'], { + skipValidation: true, + onEvent: event => { + if (event.event === 'step:retry') { + retryEvents++; + assert.equal(event.delayMs, 40); + assert.equal(active, true); + cleanup.resolve(); + } + }, + }); + await bounded(aborted.promise, 1000); + const result = await running; + assert.equal(result.status, 'success'); + assert.equal(result.retries, 1); + assert.equal(calls, 2); + assert.equal(retryEvents, 1); + }); + + it('returns a timeout promptly without a retry even if the operation never settles', async () => { + const aborted = deferred(); + const { step, api } = setup({ execute: async signal => + new Promise(() => signal?.addEventListener('abort', () => aborted.resolve(), { once: true })), + }); + const running = executeSingleStep(step, context(), api, 'admin', ['*'], { skipValidation: true }); + let settled = false; + void running.then(() => { settled = true; }, () => { settled = true; }); + await bounded(aborted.promise, 1000); + await nextTurn(); + assert.equal(settled, true, 'timeout should not wait for an unsettled request'); + assert.equal((await running).status, 'timeout'); + }); + + it('does not let a late response overwrite the timeout result', async () => { + const late = deferred<{ responseData: unknown }>(); + const { step, api } = setup({ execute: () => late.promise }); + const ctx = context(); + const result = await executeSingleStep(step, ctx, api, 'admin', ['*'], { skipValidation: true }); + assert.equal(result.status, 'timeout'); + late.resolve({ responseData: { late: true } }); + await nextTurn(); + assert.equal(ctx.steps.write.status, 'timeout'); + }); + + it('observes a late rejection after the timeout result', async () => { + const late = deferred<{ responseData: unknown }>(); + const { step, api } = setup({ execute: () => late.promise }); + const result = await executeSingleStep(step, context(), api, 'admin', ['*'], { skipValidation: true }); + assert.equal(result.status, 'timeout'); + late.reject(new Error('late abort failure')); + await nextTurn(); + }); + + it('reports TIMEOUT when the request resolves synchronously during abort', async () => { + const { step, api } = setup({ execute: async signal => + new Promise(resolve => signal?.addEventListener('abort', () => resolve({ responseData: { late: true } }), { once: true })), + }); + const result = await executeSingleStep(step, context(), api, 'admin', ['*'], { skipValidation: true }); + assert.equal(result.status, 'timeout'); + assert.equal(result.errorCode, 'TIMEOUT'); + }); + + it('does not cache a connection lookup that completes after cancellation', async () => { + const lookup = deferred(); + const { step, api } = setup({}); + step.action = { platform: 'test', actionId: step.action!.actionId, connection: { platform: 'test' } }; + (api as unknown as { listConnections: () => Promise }).listConnections = () => lookup.promise; + const ctx = context(); + const result = await executeSingleStep(step, ctx, api, 'admin', ['*'], { skipValidation: true }); + assert.equal(result.status, 'timeout'); + lookup.resolve([]); + await nextTurn(); + assert.equal(ctx._connections, undefined); + }); + + it('honors retryOn and failFastOn for timeout errors', async () => { + for (const [config, expectedCalls] of [ + [{ strategy: 'retry', retries: 1, retryDelayMs: 0, retryOn: ['TIMEOUT'] }, 2], + [{ strategy: 'retry', retries: 1, retryDelayMs: 0, failFastOn: ['TIMEOUT'] }, 1], + ] as [FlowStepErrorConfig, number][]) { + let calls = 0; + const { step, api } = setup({ execute: async signal => { + calls++; + return new Promise((_resolve, reject) => signal?.addEventListener('abort', () => reject(signal.reason), { once: true })); + } }, config); + await assert.rejects(executeSingleStep(step, context(), api, 'admin', ['*'], { skipValidation: true }), /exceeded timeout/); + assert.equal(calls, expectedCalls); + } + }); + + it('does not wait indefinitely for an operation that ignores abort', async () => { + let signal: AbortSignal | undefined; + const { step, api } = setup({ execute: async received => { + signal = received; + return new Promise(() => {}); + } }); + const result = await bounded( + executeSingleStep(step, context(), api, 'admin', ['*'], { skipValidation: true }), 1000, + ); + assert.equal(result.status, 'timeout'); + assert.equal(signal?.aborted, true); + }); + + it('applies retryDelayMs: 0 even when an abort-insensitive attempt remains active', async () => { + let calls = 0; + let firstActive = true; + let retryWhileFirstActive = false; + let retryEvents = 0; + const { step, api } = setup({ execute: async () => { + calls++; + if (calls === 1) return new Promise(() => {}); + retryWhileFirstActive = firstActive; + return { responseData: { ok: true } }; + } }, { strategy: 'retry', retries: 1, retryDelayMs: 0 }); + const result = await bounded(executeSingleStep(step, context(), api, 'admin', ['*'], { + skipValidation: true, + onEvent: event => { + if (event.event === 'step:retry') { + retryEvents++; + assert.equal(event.delayMs, 0); + } + }, + }), 1000); + firstActive = false; + assert.equal(result.status, 'success'); + assert.equal(result.retries, 1); + assert.equal(calls, 2); + assert.equal(retryEvents, 1); + assert.equal(retryWhileFirstActive, true, 'an abort-insensitive operation can still overlap a retry'); + }); + + it('can retry while an abort-aware operation is still settling after a zero delay', async () => { + const firstSettled = deferred(); + const aborted = deferred(); + let calls = 0; + let overlapped = false; + const { step, api } = setup({ execute: async signal => { + calls++; + if (calls === 1) { + return new Promise((_resolve, reject) => signal?.addEventListener('abort', () => { + aborted.resolve(); + void firstSettled.promise.then(() => reject(signal.reason)); + }, { once: true })); + } + overlapped = true; + return { responseData: { ok: true } }; + } }, { strategy: 'retry', retries: 1, retryDelayMs: 0 }); + const running = executeSingleStep(step, context(), api, 'admin', ['*'], { skipValidation: true }); + await bounded(aborted.promise, 1000); + try { + const result = await bounded(running, 1000); + assert.equal(result.status, 'success'); + assert.equal(result.retries, 1); + assert.equal(calls, 2); + assert.equal(overlapped, true); + } finally { + firstSettled.resolve(); + } + }); +}); + +describe('flow paginate timeout cancellation', () => { + function paginateSetup(execute: (page: number, signal?: AbortSignal) => Promise<{ responseData: unknown }>) { + const actionId = `paginate-timeout-test-${++nextId}`; + const step: FlowStep = { + id: 'list', name: 'List', type: 'paginate', timeoutMs: 75, onError: { strategy: 'continue' }, + paginate: { + action: { platform: 'test', actionId, connectionKey: 'test-connection' }, + pageTokenField: 'next', + resultsField: 'items', + inputTokenParam: 'queryParams.cursor', + maxPages: 20, + }, + }; + const signals: (AbortSignal | undefined)[] = []; + let requests = 0; + const api = { + getActionDetailsWithMeta: async () => ({ + data: { _id: actionId, title: 'List', method: 'GET', path: '/items', tags: [] } as ActionDetails, + status: 200, etag: null, + }), + executePassthroughRequest: async (args: { signal?: AbortSignal }) => { + signals.push(args.signal); + return execute(requests++, args.signal); + }, + } as unknown as OneApi; + return { step, api, signals, requests: () => requests }; + } + + it('aborts the in-flight page and fetches no more after the timeout', async () => { + const { step, api, signals, requests } = paginateSetup(async (page, signal) => { + if (page === 0) return { responseData: { items: [page], next: 'cursor-1' } }; + return new Promise((_resolve, reject) => signal?.addEventListener('abort', () => reject(signal.reason), { once: true })); + }); + const pageEvents: number[] = []; + const result = await bounded(executeSingleStep(step, context(), api, 'admin', ['*'], { + skipValidation: true, + onEvent: event => { if (event.event === 'step:page') pageEvents.push(event.page as number); }, + }), 1000); + assert.equal(result.status, 'timeout'); + assert.equal(result.errorCode, 'TIMEOUT'); + await new Promise(resolve => setTimeout(resolve, 150)); + assert.equal(requests(), 2, 'no page is fetched after the timeout'); + assert.deepEqual(pageEvents, [1]); + assert.ok(signals.every(signal => signal?.aborted), 'every page request carries the aborted step signal'); + }); + + it('does not fetch the next page when a page resolves after the timeout', async () => { + const late = deferred<{ responseData: unknown }>(); + const { step, api, requests } = paginateSetup(async page => + page === 0 ? late.promise : { responseData: { items: [page], next: `cursor-${page + 1}` } }, + ); + const pageEvents: number[] = []; + const result = await bounded(executeSingleStep(step, context(), api, 'admin', ['*'], { + skipValidation: true, + onEvent: event => { if (event.event === 'step:page') pageEvents.push(event.page as number); }, + }), 1000); + assert.equal(result.status, 'timeout'); + late.resolve({ responseData: { items: [0], next: 'cursor-1' } }); + await new Promise(resolve => setTimeout(resolve, 50)); + assert.equal(requests(), 1, 'a late page must not start another request'); + assert.deepEqual(pageEvents, []); + }); +}); diff --git a/src/lib/flow-engine.ts b/src/lib/flow-engine.ts index 511ef5d..2d29de6 100644 --- a/src/lib/flow-engine.ts +++ b/src/lib/flow-engine.ts @@ -54,6 +54,27 @@ function withTimeout(promise: Promise, timeoutMs: number, stepId: string): }) as Promise; } +async function withActionTimeout( + operation: Promise, timeoutMs: number, stepId: string, controller: AbortController, +): Promise { + let timer: NodeJS.Timeout | undefined; + const deadline = new Promise((_, reject) => { + timer = setTimeout(() => { + const timeoutError = new StepTimeoutError(stepId, timeoutMs); + // Queue the timeout result before abort listeners can settle the action. + // A request that resolves as a consequence of abort is still timed out. + reject(timeoutError); + controller.abort(timeoutError); + }, timeoutMs); + }); + try { + return await Promise.race([operation, deadline]); + } finally { + // Promise.race observes a late rejection from the aborted operation. + if (timer) clearTimeout(timer); + } +} + /** * Thrown when a `file-read` step's parsed output fails its declared * `fileRead.schema`. Carries `errorCode: 'SCHEMA_VALIDATION'` so it rides the @@ -740,9 +761,10 @@ async function executeActionStep( permissions: PermissionLevel, allowedActionIds: string[], options: FlowExecuteOptions, + signal?: AbortSignal, ): Promise { const resolved = resolveValue(step.action!, context) as FlowActionConfig; - return executeResolvedAction(step.id, resolved, context, api, permissions, allowedActionIds, options); + return executeResolvedAction(step.id, resolved, context, api, permissions, allowedActionIds, options, signal); } /** @@ -761,7 +783,9 @@ async function executeResolvedAction( permissions: PermissionLevel, allowedActionIds: string[], options: FlowExecuteOptions, + signal?: AbortSignal, ): Promise { + signal?.throwIfAborted(); const platform = action.platform as string; const actionId = action.actionId as string; @@ -792,9 +816,13 @@ async function executeResolvedAction( // flow does ONE listConnections per run. const ref = action.connection as { platform: string; tag?: string }; if (!context._connections) { - context._connections = await api.listConnections(); + const connections = await api.listConnections(signal); + signal?.throwIfAborted(); + context._connections = connections; } + signal?.throwIfAborted(); const conn = await api.resolveConnection(ref, context._connections); + signal?.throwIfAborted(); connectionKey = conn.key; } @@ -808,7 +836,8 @@ async function executeResolvedAction( throw new Error(`Action "${actionId}" is not in the allowed action list`); } - const { details: actionDetails } = await resolveActionDetails(api, actionId); + const { details: actionDetails } = await resolveActionDetails(api, actionId, { signal }); + signal?.throwIfAborted(); if (!isMethodAllowed(actionDetails.method, permissions)) { throw new Error(`Method "${actionDetails.method}" is not allowed under "${permissions}" permission level`); } @@ -832,6 +861,7 @@ async function executeResolvedAction( pathVariables: pathVars, queryParams, headers, + signal, }, actionDetails); return { @@ -1334,6 +1364,7 @@ async function executePaginateStep( permissions: PermissionLevel, allowedActionIds: string[], options: FlowExecuteOptions, + signal?: AbortSignal, ): Promise { const config = step.paginate!; const maxPages = config.maxPages ?? 10; @@ -1347,13 +1378,16 @@ async function executePaginateStep( const resolvedTemplate = resolveValue(config.action, context) as FlowActionConfig; for (let page = 0; page < maxPages; page++) { + // A timed-out paginate step must not fetch (or report) another page. + signal?.throwIfAborted(); const actionConfig = structuredClone(resolvedTemplate) as FlowActionConfig; if (page > 0) { setByDotPath(actionConfig as unknown as Record, config.inputTokenParam, pageToken); } const result = await executeResolvedAction( - `${step.id}__page${page}`, actionConfig, context, api, permissions, allowedActionIds, options, + `${step.id}__page${page}`, actionConfig, context, api, permissions, allowedActionIds, options, signal, ); + signal?.throwIfAborted(); const response = result.response as Record; const pageResults = getByDotPath(response, config.resultsField); if (Array.isArray(pageResults)) allResults.push(...pageResults); @@ -1629,10 +1663,14 @@ export async function executeSingleStep( return result; } + // Action-backed steps get a signal so a timeout cancels their requests. + const actionController = step.type === 'action' || step.type === 'paginate' + ? new AbortController() + : undefined; const dispatch = async (): Promise => { switch (step.type) { case 'action': - return await executeActionStep(step, context, api, permissions, allowedActionIds, options); + return await executeActionStep(step, context, api, permissions, allowedActionIds, options, actionController?.signal); case 'transform': return await executeTransformStep(step, context); case 'code': @@ -1655,7 +1693,7 @@ export async function executeSingleStep( case 'flow': return await executeSubflowStep(step, context, api, permissions, allowedActionIds, options, flowStack); case 'paginate': - return await executePaginateStep(step, context, api, permissions, allowedActionIds, options); + return await executePaginateStep(step, context, api, permissions, allowedActionIds, options, actionController?.signal); case 'bash': return await executeBashStep(step, context, options); default: @@ -1663,9 +1701,12 @@ export async function executeSingleStep( } }; + const operation = dispatch(); const result: StepResult = step.timeoutMs - ? await withTimeout(dispatch(), step.timeoutMs, step.id) - : await dispatch(); + ? actionController + ? await withActionTimeout(operation, step.timeoutMs, step.id, actionController) + : await withTimeout(operation, step.timeoutMs, step.id) + : await operation; result.durationMs = Date.now() - startTime; if (attempt > 1) { diff --git a/src/lib/flow-schema.ts b/src/lib/flow-schema.ts index 49f69a7..9742130 100644 --- a/src/lib/flow-schema.ts +++ b/src/lib/flow-schema.ts @@ -70,7 +70,7 @@ export const FLOW_SCHEMA: FlowSchemaDescriptor = { type: { type: 'string', required: true, description: 'Step type (determines which config object is required)' }, if: { type: 'string', required: false, description: 'JS expression — skip step if falsy' }, unless: { type: 'string', required: false, description: 'JS expression — skip step if truthy' }, - timeoutMs: { type: 'number', required: false, description: 'Wall-clock timeout (ms). On expiry the step fails with errorCode:"TIMEOUT"; with onError:continue the result gets status:"timeout".' }, + timeoutMs: { type: 'number', required: false, description: 'Wall-clock timeout (ms). On expiry the step fails with errorCode:"TIMEOUT"; with onError:continue the result gets status:"timeout". Action and paginate steps abort their request; other step types keep running in the background.' }, requires: { type: 'array', required: false, description: 'Presence preconditions: array of $.input.X or $.steps.X.output... selectors that must resolve to a non-empty value before the step runs. Failures honor onError.' }, outputSchema: { type: 'object', required: false, description: 'Optional declaration of the shape this step\'s output produces. When set, the validator checks that downstream $.steps..output. references point at declared fields. Format: { fieldName: "string"|"number"|"boolean"|"object"|"array"|"unknown" } — nested objects are supported.' }, }, @@ -675,6 +675,8 @@ Strategies: \`${FLOW_SCHEMA.errorStrategies.join('\`, \`')}\` } \`\`\` +When an action or paginate step sets timeoutMs, the CLI aborts its local preflight and request on timeout, and a paginate step fetches no further pages. Other step types keep running in the background after a timeout, including the steps inside a timed-out loop, parallel, while or flow step. A configured retry follows the existing retryDelayMs and backoff policy; the earlier operation may still be active when the retry begins, especially with retryDelayMs: 0. Aborting locally does not guarantee a remote write was rolled back: a write cancelled mid-request may or may not have reached the destination. Use the destination's idempotency support for stronger protection against duplicate writes. + ## Step Output Contracts (\`outputSchema\`, cli#59) Declare a step's output shape so the validator catches downstream field-name typos at flow load time: diff --git a/src/lib/types.ts b/src/lib/types.ts index 78c9042..80fa790 100644 --- a/src/lib/types.ts +++ b/src/lib/types.ts @@ -230,6 +230,8 @@ export interface ExecuteActionArgs { platform: string; actionId: string; connectionKey: string; + /** Optional cancellation for preflight and the passthrough request. */ + signal?: AbortSignal; data?: any; pathVariables?: Record; queryParams?: Record;