Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 62 additions & 0 deletions .github/workflows/fi-core-attachments-tests.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
name: TypeScript attachment core
on:
pull_request:
paths:
- 'typescript/packages/fi-core/**'
- 'typescript/packages/fi-semantic-conventions/**'
- '.github/workflows/fi-core-attachments-tests.yml'
workflow_dispatch:
permissions:
contents: read
jobs:
runtime:
runs-on: ubuntu-24.04
timeout-minutes: 15
strategy:
fail-fast: false
matrix:
node: ['18', '24']
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node }}
- uses: pnpm/action-setup@v4
with:
version: 10.30.1
- name: Fetch pinned F01 contract fixtures
uses: actions/checkout@v4
with:
ref: f3b0923c62d43b3a52bf4c16a2226c39c22b690d
path: attachment-contract
persist-credentials: false
- name: Build core and run synthetic attachment boundaries
working-directory: typescript
env:
FI_ATTACHMENTS_SPEC_DIR: ${{ github.workspace }}/attachment-contract/spec/attachments/v1
run: |
pnpm --filter @traceai/fi-core... install --frozen-lockfile --ignore-scripts
pnpm --filter @traceai/fi-semantic-conventions run build
pnpm --filter @traceai/fi-core run build
pnpm --filter @traceai/fi-core run test:attachments
- name: Test installed OTel floor and latest qualified release
if: matrix.node == '24'
working-directory: typescript
run: |
mkdir -p "$RUNNER_TEMP/attachment-packs"
pnpm --dir packages/fi-core pack --pack-destination "$RUNNER_TEMP/attachment-packs"
pnpm --dir packages/fi-semantic-conventions pack --pack-destination "$RUNNER_TEMP/attachment-packs"
for version in 2.0.1 2.12.1; do
node packages/fi-core/test/install-sdk-fixture.cjs "$version" "$RUNNER_TEMP/attachment-sdk-$version" "$RUNNER_TEMP"/attachment-packs/traceai-fi-core-*.tgz "$RUNNER_TEMP"/attachment-packs/traceai-fi-semantic-conventions-*.tgz
FI_CORE_PACKAGE_JSON="$RUNNER_TEMP/attachment-sdk-$version/node_modules/@traceai/fi-core/package.json" FI_ATTACHMENTS_SPEC_DIR="$GITHUB_WORKSPACE/attachment-contract/spec/attachments/v1" node --test packages/fi-core/test/attachments.test.cjs packages/fi-core/test/attachments-tls.test.cjs packages/fi-core/test/attachments-design.test.cjs packages/fi-core/test/attachments-files.test.cjs packages/fi-core/test/attachments-exit.test.cjs packages/fi-core/test/attachments-wire.test.cjs packages/fi-core/test/attachments-deferred.test.cjs packages/fi-core/test/provider-lifecycle.test.cjs
done
- name: Replay privacy and identity fixture safety
run: node typescript/packages/fi-core/test/attachments-contract.cjs attachment-contract/spec/attachments/v1
- name: Qualify browser-safe leaf
if: matrix.node == '24'
working-directory: typescript/packages/fi-core
run: |
npm install --prefix "$RUNNER_TEMP/attachment-tools" --no-audit --no-fund esbuild@0.25.12 playwright@1.56.1
"$RUNNER_TEMP/attachment-tools/node_modules/.bin/playwright" install --with-deps chromium
"$RUNNER_TEMP/attachment-tools/node_modules/.bin/esbuild" dist/esm/attachments/index.js --bundle --platform=browser --format=iife --global-name=Attachments --outfile="$RUNNER_TEMP/attachments-browser.js"
node test/attachments-browser.cjs "$RUNNER_TEMP/attachment-tools/node_modules/playwright" "$RUNNER_TEMP/attachments-browser.js"
24 changes: 24 additions & 0 deletions typescript/packages/fi-core/ATTACHMENTS-MIGRATION.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Attachments API migration (`@traceai/fi-core/attachments`)

The streaming, recording and import work changed a few behaviours that integrations built against the first attachment runtime depend on. Earlier, some of these changes broke callers silently: capture just stopped. Each one now fails loudly, as a compile error, a one-time process warning with a stable code, or an explicit reason at the call. This page lists each change and what to do about it.

| Change | Old | New | How it fails now | What to change |
|---|---|---|---|---|
| Ready state | `status().state === "queued"` | `status().state === "ready"` | TypeScript: TS2367 on any comparison with `"queued"`. JavaScript: the comparison is always false, so check for `"ready"`. | Compare with `"ready"`. Admission results (`handle.admission`, `ticket.reason`, `writer.reason`) still use `"queued"` for "admitted". |
| Completion `failed` | `completion.status === "failed"` | `"incomplete"` (transport or unknown) or `"unsupported_version"` (invalid response shape) | TypeScript: TS2367. `failed` is no longer in `AttachmentCompletion`. | Treat any status other than `validating` / `importing` as not delivered. A legacy transport that still throws `AttachmentTransportError("failed")` is mapped to `incomplete`. |
| Four-method transport (`bootstrap` / `initialize` / `upload` / `complete`) | Full support | Adapted, with reduced capability | Warns once per process: `DeprecationWarning` code `FI_ATTACHMENTS_LEGACY_TRANSPORT`. `startRecording`, WAV-tier `attachOwnedRecording` and `importCompletedRecording` return `unsupported_version` at the call, so no bytes are buffered or uploaded. Sessions cannot renew, so capture reports `expired` after the first session lifetime. | Pass `createAttachmentHttpTransportV1(...)` or implement `AttachmentTransportV1`. A wrapper around `createAttachmentHttpTransport(...)` must forward its `[ATTACHMENT_TRANSPORT_V1]` member, or wrap the V1 surface directly. Otherwise the wrapper silently becomes legacy. |
| Strict F01 response shapes | Lenient | Every response is checked against F01 (for example, status bodies need `reason`) | The affected attachment reports `unsupported_version`, and a warning with code `FI_ATTACHMENTS_WIRE_REJECTED` names the shape once, such as `UploadStatus` or `AttachmentSession`. The warning contains no values. | Make the server or test double match `spec/attachments/v1`. |
| Session renewal triggers | Only admission calls (`preflight`, `attach`, ...) | Also `status()`, `flush()`, worker wake and recording writes (design 3.1) | Not an error. HTTP doubles that mint short sessions see an extra `POST /tracer/v1/attachment-sessions` with `Idempotency-Key: bs-{session}-{n}` near expiry. | Mint sessions of one hour or more in doubles, or expect the renewal request. |
| `manager.correlation(span)` | Stamped `fi.attachment.*` on the span | Returns a snapshot only. Stamping happens when a capture is admitted (design 0.8). | Not an error: a span without an admitted capture carries no attachment attributes, which is intended. | Pass the correlation (or the span) to `attach` / `preflight` / `startRecording`. Do not rely on `correlation()` alone to mark a span. |

## Warnings

Both warning codes are exported as `ATTACHMENT_WARNING_LEGACY_TRANSPORT` and `ATTACHMENT_WARNING_WIRE_REJECTED`. On Node they go through `process.emitWarning`, so `--no-deprecation` and `--no-warnings` apply. In browsers they go to `console.warn`. Each is emitted at most once per process, per code and shape.

## Additions (non-breaking)

| Addition | Behaviour |
|---|---|
| `manager.deferredCorrelation({ bindTimeoutMs })` returns an `AttachmentDeferredCorrelation` | A capture target for a span that does not exist yet, such as a wire span emitted only after the response body completes. `preflight`, `attach` and `startAttachmentStream` admit `Bytes`, `Blob` and consumed-stream captures against it using the full deny-wins check. Committed bytes stay in the owned budget, capped at half of it, and nothing is sent. `target.bind(span)` checks policy and sampling again, then uploads against that span and projects the references onto it. The sampling check covers every capture on the target: parked captures, streams still open at bind and tickets committed after bind all end `unsampled` on an unsampled or non-recording span. If the bind timeout passes (default 60 s, max 300 s, checked lazily without a timer), `target.cancel()` is called or the manager shuts down, pending captures end `correlation_unavailable` and upload nothing. A late `bind` (after the timeout) returns false, binds nothing and cancels the target, so open streams and outstanding tickets also end `correlation_unavailable`. Owned files, recordings and imports never defer. If a span already has a correlation, the bound target forwards to it, so the span keeps one reference list. |
| `startAttachmentStream` reservation | The reservation is `min(maxBytes, negotiated single-upload cap)`. A server whose `max_upload_bytes` is below an adapter's default (for example 4 MiB) still admits the stream, and a body larger than the effective cap is discarded whole (`too_large`). `preflight` keeps its exact semantics: a `maxBytes` over the cap is `too_large`. |
| `shutdown()` after `invalidate(reason)` | The state stays `reason` (`policy_denied`, `deleted`, `expired`); before this change, `shutdown()` overwrote it with `incomplete`. |
14 changes: 13 additions & 1 deletion typescript/packages/fi-core/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -12,19 +12,30 @@
"import": "./dist/esm/index.js",
"require": "./dist/src/index.js"
},
"./attachments": {
"types": "./dist/src/attachments/index.d.ts",
"import": "./dist/esm/attachments/index.js",
"require": "./dist/src/attachments/index.js"
},
"./attachments/node": {
"types": "./dist/src/attachments/node.d.ts",
"import": "./dist/esm/attachments/node.js",
"require": "./dist/src/attachments/node.js"
},
"./privacy": {
"types": "./dist/src/privacy-runtime.d.ts",
"import": "./dist/esm/privacy.js",
"require": "./dist/src/privacy-runtime.js"
}
},
"typesVersions": { "*": { "privacy": ["dist/src/privacy-runtime.d.ts"] } },
"typesVersions": { "*": { "privacy": ["dist/src/privacy-runtime.d.ts"], "attachments": ["dist/src/attachments/index.d.ts"], "attachments/node": ["dist/src/attachments/node.d.ts"] } },
"scripts": {
"prebuild": "rimraf dist",
"build": "tsc --build tsconfig.json tsconfig.esm.json tsconfig.esnext.json && tsc-alias -p tsconfig.esm.json && pnpm run postbuild",
"postbuild": "node scripts/postbuild.cjs",
"test": "jest",
"test:provider": "node --test test/provider-lifecycle.test.cjs",
"test:attachments": "node --test test/attachments.test.cjs test/attachments-tls.test.cjs test/attachments-design.test.cjs test/attachments-files.test.cjs test/attachments-exit.test.cjs test/attachments-wire.test.cjs test/attachments-compat.test.cjs test/attachments-deferred.test.cjs",
"test:watch": "jest --watch",
"test:coverage": "jest --coverage",
"lint": "eslint . --ext .ts",
Expand All @@ -33,6 +44,7 @@
"files": [
"dist",
"README.md",
"ATTACHMENTS-MIGRATION.md",
"src"
],
"repository": {
Expand Down
10 changes: 10 additions & 0 deletions typescript/packages/fi-core/scripts/postbuild.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -16,3 +16,13 @@ for (const dir of ['dist/esm', 'dist/esnext']) {
fs.writeFileSync(`${dir}/${name}.js`, `export { ${runtimeExports.join(', ')} } from "../src/privacy-runtime.js";\n`);
}
}

// A provider and an adapter may import different module formats. Keep correlation
// class identity (and its private span references) identical across those imports.
for (const name of ['index', 'manager', 'correlation', 'policy', 'transport-v1', 'node', 'disabled', 'admission', 'stream', 'recording', 'imports', 'owned', 'node-sources', 'wire']) {
const exports = Object.keys(require(`../dist/src/attachments/${name}.js`));
if (!exports.every(key => /^[A-Za-z_$][\w$]*$/.test(key))) throw new Error('postbuild: unexpected attachment export');
for (const dir of ['dist/esm', 'dist/esnext']) {
fs.writeFileSync(`${dir}/attachments/${name}.js`, `export { ${exports.join(', ')} } from "../../src/attachments/${name}.js";\n`);
}
}
50 changes: 50 additions & 0 deletions typescript/packages/fi-core/src/attachments/admission.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
import type { AttachmentCorrelation } from "./correlation";
import type { AdmissionFacts } from "./internal";
import type {
AttachmentAdmission, AttachmentAdmissionTicket, AttachmentFields, AttachmentHandle, AttachmentSource, AttachmentStream, AttachmentStreamOptions,
} from "./types";

/** @internal */
export interface TicketHost {
commitTicket(ticket: AttachmentTicket, source: Extract<AttachmentSource, { kind: "Bytes" | "Blob" | "OwnedRecordingFile" }>, fields: AttachmentFields): AttachmentHandle;
commitStream(ticket: AttachmentTicket, options: AttachmentStreamOptions): AttachmentStream;
releaseReservation(id: number): void;
deniedHandle(reason: AttachmentAdmission): AttachmentHandle;
deniedStream(reason: AttachmentAdmission): AttachmentStream;
}
/**
* Single-use preflight ticket (design 1.5). It holds a reservation id only, never the source; the manager tracks the
* reservation by id so an abandoned ticket can be collected and its budget returned by a finalizer.
*/
export class AttachmentTicket implements AttachmentAdmissionTicket {
/** @internal */ used = false;
constructor(
private readonly host: TicketHost,
readonly reason: AttachmentAdmission,
readonly maxBytes: number,
readonly correlation: AttachmentCorrelation | undefined,
/** @internal */ readonly facts: AdmissionFacts | undefined,
/** @internal */ readonly reservation: number,
/** @internal */ readonly expiresAt: number,
) {}
get admitted(): boolean { return this.reason === "queued"; }
attach(source: Extract<AttachmentSource, { kind: "Bytes" | "Blob" | "OwnedRecordingFile" }>, fields: AttachmentFields = {}): AttachmentHandle {
try {
if (!this.admitted) return this.host.deniedHandle(this.reason);
if (this.used) return this.host.deniedHandle("conflict" as AttachmentAdmission);
return this.host.commitTicket(this, source, fields ?? {});
} catch { return this.host.deniedHandle("source_unavailable"); }
}
startStream(options: AttachmentStreamOptions): AttachmentStream {
try {
if (!this.admitted) return this.host.deniedStream(this.reason);
if (this.used) return this.host.deniedStream("conflict" as AttachmentAdmission);
return this.host.commitStream(this, options);
} catch { return this.host.deniedStream("source_unavailable"); }
}
release(): void {
if (this.used || !this.admitted) return;
this.used = true;
this.host.releaseReservation(this.reservation);
}
}
Loading
Loading