@outputai/http 0.2.1-next.af8a069.0 → 0.2.1-next.b87b58f.0

package/dist/consts.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Symbol used to store request id in the response object.
+ */
+export declare const requestIdSymbol: unique symbol;

package/dist/consts.js

@@ -0,0 +1,4 @@
+/**
+ * Symbol used to store request id in the response object.
+ */
+export const requestIdSymbol = Symbol('request_id');

package/dist/cost.d.ts

@@ -0,0 +1,16 @@
+import { KyResponse } from 'ky';
+export type RequestCost = {
+    total: number;
+    components?: Array<{
+        name: string;
+        value: number;
+    }>;
+};
+/**
+ * Attach cost information to the trace of an HTTP Request using the response
+ *
+ * @param response - The response of the HTTP Request to attach the information
+ * @param cost - The cost information
+ * @returns
+ */
+export declare const addRequestCost: (response: KyResponse | Response, cost: RequestCost) => void;

package/dist/cost.js

@@ -0,0 +1,18 @@
+import { Tracing, emitEvent } from '@outputai/core/sdk_activity_integration';
+import { requestIdSymbol } from './consts.js';
+/**
+ * Attach cost information to the trace of an HTTP Request using the response
+ *
+ * @param response - The response of the HTTP Request to attach the information
+ * @param cost - The cost information
+ * @returns
+ */
+export const addRequestCost = (response, cost) => {
+    const eventId = Reflect.get(response, requestIdSymbol);
+    if (!eventId) {
+        console.warn('addRequestCost(): The "response" argument did not originate from @outputai/http, no costs were added.');
+        return;
+    }
+    Tracing.addEventAttribute({ eventId, name: Tracing.Attribute.COST, value: cost });
+    emitEvent('cost:http:request', { requestId: eventId, url: response.url, cost });
+};

package/dist/cost.spec.js

@@ -0,0 +1,88 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { requestIdSymbol } from './consts.js';
+vi.mock('@outputai/core/sdk_activity_integration', () => ({
+    Tracing: {
+        addEventAttribute: vi.fn(),
+        Attribute: {
+            COST: 'cost'
+        }
+    },
+    emitEvent: vi.fn()
+}));
+import { Tracing, emitEvent } from '@outputai/core/sdk_activity_integration';
+import { addRequestCost } from './cost.js';
+const tracing = vi.mocked(Tracing, true);
+const emit = vi.mocked(emitEvent, true);
+describe('addRequestCost', () => {
+    beforeEach(() => {
+        tracing.addEventAttribute.mockClear();
+        emit.mockClear();
+        vi.spyOn(console, 'warn').mockImplementation(() => { });
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('shortcircuits when the response has no http request id', () => {
+        const response = new Response();
+        const cost = { total: 1 };
+        addRequestCost(response, cost);
+        expect(console.warn).toHaveBeenCalledWith('addRequestCost(): The "response" argument did not originate from @outputai/http, no costs were added.');
+        expect(tracing.addEventAttribute).not.toHaveBeenCalled();
+        expect(emit).not.toHaveBeenCalled();
+    });
+    it('records cost on the trace event when the response carries the request id', () => {
+        const response = new Response(undefined, { status: 200 });
+        Reflect.set(response, requestIdSymbol, 'evt-cost-1');
+        const cost = { total: 2.5 };
+        addRequestCost(response, cost);
+        expect(console.warn).not.toHaveBeenCalled();
+        expect(tracing.addEventAttribute).toHaveBeenCalledWith({
+            eventId: 'evt-cost-1',
+            name: Tracing.Attribute.COST,
+            value: cost
+        });
+        expect(emit).toHaveBeenCalledWith('cost:http:request', {
+            requestId: 'evt-cost-1',
+            url: response.url,
+            cost
+        });
+    });
+    it('forwards multiple components to tracing', () => {
+        const response = new Response();
+        Reflect.set(response, requestIdSymbol, 'evt-cost-2');
+        const cost = {
+            total: 10,
+            components: [
+                { name: 'input', value: 3 },
+                { name: 'output', value: 7 }
+            ]
+        };
+        addRequestCost(response, cost);
+        expect(tracing.addEventAttribute).toHaveBeenCalledWith({
+            eventId: 'evt-cost-2',
+            name: Tracing.Attribute.COST,
+            value: cost
+        });
+        expect(emit).toHaveBeenCalledWith('cost:http:request', {
+            requestId: 'evt-cost-2',
+            url: response.url,
+            cost
+        });
+    });
+    it('forwards an empty components array to tracing', () => {
+        const response = new Response();
+        Reflect.set(response, requestIdSymbol, 'evt-cost-3');
+        const cost = { total: 1, components: [] };
+        addRequestCost(response, cost);
+        expect(tracing.addEventAttribute).toHaveBeenCalledWith({
+            eventId: 'evt-cost-3',
+            name: Tracing.Attribute.COST,
+            value: cost
+        });
+        expect(emit).toHaveBeenCalledWith('cost:http:request', {
+            requestId: 'evt-cost-3',
+            url: response.url,
+            cost
+        });
+    });
+});

package/dist/fetch/index.d.ts

@@ -0,0 +1,22 @@
+import type { RequestInfo, RequestInit } from 'undici';
+/** Re-export undici library for convenience. */
+export * as undici from 'undici';
+/** Export fetch input types. Also available under in undici.* export. */
+export type { 
+/** Undici's fetch first argument: Either a URL string, a URL object or a undici.Request object. */
+RequestInfo, 
+/** Undici's fetch second argument: A plain object containing HTTP options. */
+RequestInit };
+/**
+ * A fetch compliant function, that wraps undici's fetch.
+ *
+ * Behaves the same as any fetch function except:
+ * - Sets a request header called `x-request--trace-id` with a random UUID;
+ * - Sends the request, response, error and/or failure to the Trace system;
+ *
+ * @see {@link https://fetch.spec.whatwg.org/}
+ * @param input - URL string, URL object or Request object (undici's or Node's)
+ * @param init - Request options
+ * @returns The HTTP response
+ */
+export declare const fetch: (input: RequestInfo | Request, init?: RequestInit) => Promise<Response>;

package/dist/fetch/index.js

@@ -0,0 +1,48 @@
+import * as undici from 'undici';
+import { randomUUID } from 'node:crypto';
+import { logRequest, logResponse, logError, logFailure } from './logger.js';
+import { addRequestIdToResponse } from './utils.js';
+/*
+ * Unifies undici and nodes realms
+ * https://github.com/nodejs/undici#keep-fetch-and-formdata-together
+ */
+undici.install();
+/** Re-export undici library for convenience. */
+export * as undici from 'undici';
+/**
+ * A fetch compliant function, that wraps undici's fetch.
+ *
+ * Behaves the same as any fetch function except:
+ * - Sets a request header called `x-request--trace-id` with a random UUID;
+ * - Sends the request, response, error and/or failure to the Trace system;
+ *
+ * @see {@link https://fetch.spec.whatwg.org/}
+ * @param input - URL string, URL object or Request object (undici's or Node's)
+ * @param init - Request options
+ * @returns The HTTP response
+ */
+export const fetch = async (input, init) => {
+    // Creates a Request object with the many shapes RequestInfo can have
+    const base = new undici.Request(input, init);
+    // Creates a headers object with the many shapes Request.Headers can have (object, array, Headers)
+    const headers = new undici.Headers(base.headers);
+    const requestId = randomUUID();
+    headers.set('x-request-trace-id', requestId);
+    const request = new undici.Request(base, { headers });
+    await logRequest({ requestId, request });
+    try {
+        const response = await undici.fetch(request);
+        // This enriches the response of the request id, so it is identifiable later.
+        addRequestIdToResponse(response, requestId);
+        if (response.status > 399) {
+            await logError({ requestId, response });
+            return response;
+        }
+        await logResponse({ requestId, response });
+        return response;
+    }
+    catch (error) {
+        logFailure({ requestId, error: error });
+        throw error;
+    }
+};

package/dist/fetch/index.spec.js

@@ -0,0 +1,218 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { getGlobalDispatcher, Headers, MockAgent, Request, setGlobalDispatcher } from 'undici';
+const FIXED_REQUEST_ID = 'aaaaaaaa-bbbb-4ccc-dddd-eeeeeeeeeeee';
+const randomUUIDMock = vi.hoisted(() => vi.fn(() => FIXED_REQUEST_ID));
+const loggerMock = vi.hoisted(() => ({
+    logRequest: vi.fn(async (_args) => { }),
+    logResponse: vi.fn(async (_args) => { }),
+    logError: vi.fn((_args) => { }),
+    logFailure: vi.fn((_args) => { })
+}));
+const utilsMock = vi.hoisted(() => ({
+    addRequestIdToResponse: vi.fn()
+}));
+vi.mock('node:crypto', () => ({
+    randomUUID: () => randomUUIDMock()
+}));
+vi.mock('./logger.js', () => ({
+    logRequest: loggerMock.logRequest,
+    logResponse: loggerMock.logResponse,
+    logError: loggerMock.logError,
+    logFailure: loggerMock.logFailure
+}));
+vi.mock('./utils.js', () => ({
+    addRequestIdToResponse: utilsMock.addRequestIdToResponse
+}));
+import { fetch } from './index.js';
+const MOCK_ORIGIN = 'https://fetch-index.undici.test';
+describe('fetch/index', () => {
+    const undiciCtx = {
+        mockAgent: undefined,
+        previousDispatcher: undefined
+    };
+    beforeEach(() => {
+        undiciCtx.mockAgent = new MockAgent();
+        undiciCtx.mockAgent.disableNetConnect();
+        undiciCtx.previousDispatcher = getGlobalDispatcher();
+        setGlobalDispatcher(undiciCtx.mockAgent);
+        loggerMock.logRequest.mockClear();
+        loggerMock.logResponse.mockClear();
+        loggerMock.logError.mockClear();
+        loggerMock.logFailure.mockClear();
+        utilsMock.addRequestIdToResponse.mockClear();
+        randomUUIDMock.mockClear();
+        randomUUIDMock.mockImplementation(() => FIXED_REQUEST_ID);
+    });
+    afterEach(async () => {
+        if (undiciCtx.previousDispatcher !== undefined) {
+            setGlobalDispatcher(undiciCtx.previousDispatcher);
+        }
+        if (undiciCtx.mockAgent !== undefined) {
+            await undiciCtx.mockAgent.close();
+        }
+    });
+    describe('fetch with MockAgent', () => {
+        it('returns 200, traces request start and response end', async () => {
+            undiciCtx.mockAgent.get(MOCK_ORIGIN).intercept({ path: '/ok', method: 'GET' }).reply(200, 'hello', { headers: { 'content-type': 'text/plain' } });
+            const response = await fetch(`${MOCK_ORIGIN}/ok`);
+            expect(response.status).toBe(200);
+            expect(await response.text()).toBe('hello');
+            expect(loggerMock.logRequest).toHaveBeenCalledTimes(1);
+            expect(loggerMock.logRequest.mock.calls[0][0].requestId).toBe(FIXED_REQUEST_ID);
+            expect(loggerMock.logRequest.mock.calls[0][0].request.method).toBe('GET');
+            expect(loggerMock.logRequest.mock.calls[0][0].request.url).toBe(`${MOCK_ORIGIN}/ok`);
+            expect(loggerMock.logResponse).toHaveBeenCalledTimes(1);
+            expect(loggerMock.logResponse.mock.calls[0][0].requestId).toBe(FIXED_REQUEST_ID);
+            expect(loggerMock.logResponse.mock.calls[0][0].response).toBe(response);
+            expect(utilsMock.addRequestIdToResponse).toHaveBeenCalledTimes(1);
+            expect(utilsMock.addRequestIdToResponse).toHaveBeenCalledWith(response, FIXED_REQUEST_ID);
+            expect(loggerMock.logError).not.toHaveBeenCalled();
+            expect(loggerMock.logFailure).not.toHaveBeenCalled();
+        });
+        it('uses logError for status > 399 without logging response end', async () => {
+            undiciCtx.mockAgent.get(MOCK_ORIGIN).intercept({ path: '/missing', method: 'GET' }).reply(404, 'nope', { headers: { 'content-type': 'text/plain' } });
+            const response = await fetch(`${MOCK_ORIGIN}/missing`);
+            expect(response.status).toBe(404);
+            expect(loggerMock.logRequest).toHaveBeenCalledTimes(1);
+            expect(loggerMock.logResponse).not.toHaveBeenCalled();
+            expect(loggerMock.logError).toHaveBeenCalledTimes(1);
+            expect(loggerMock.logError.mock.calls[0][0].requestId).toBe(FIXED_REQUEST_ID);
+            expect(loggerMock.logError.mock.calls[0][0].response).toBe(response);
+            expect(utilsMock.addRequestIdToResponse).toHaveBeenCalledTimes(1);
+            expect(utilsMock.addRequestIdToResponse).toHaveBeenCalledWith(response, FIXED_REQUEST_ID);
+        });
+        it('treats status 399 as success (logs response end, not HTTP error)', async () => {
+            undiciCtx.mockAgent.get(MOCK_ORIGIN).intercept({ path: '/edge', method: 'GET' }).reply(399, '', { headers: { 'content-type': 'text/plain' } });
+            const response = await fetch(`${MOCK_ORIGIN}/edge`);
+            expect(response.status).toBe(399);
+            expect(loggerMock.logResponse).toHaveBeenCalledTimes(1);
+            expect(loggerMock.logError).not.toHaveBeenCalled();
+        });
+        it('sends x-request-trace-id and custom headers when init.headers is a plain object', async () => {
+            undiciCtx.mockAgent.get(MOCK_ORIGIN).intercept({
+                path: '/with-plain-headers',
+                method: 'GET',
+                headers: {
+                    'x-request-trace-id': FIXED_REQUEST_ID,
+                    'x-custom': 'plain-value'
+                }
+            }).reply(200, 'ok');
+            const response = await fetch(`${MOCK_ORIGIN}/with-plain-headers`, {
+                headers: { 'X-Custom': 'plain-value' }
+            });
+            expect(response.status).toBe(200);
+            const { request } = loggerMock.logRequest.mock.calls[0][0];
+            expect(request.headers.get('x-request-trace-id')).toBe(FIXED_REQUEST_ID);
+            expect(request.headers.get('x-custom')).toBe('plain-value');
+        });
+        it('sends x-request-trace-id and custom headers when init.headers is a Headers instance', async () => {
+            undiciCtx.mockAgent.get(MOCK_ORIGIN).intercept({
+                path: '/with-headers-instance',
+                method: 'GET',
+                headers: {
+                    'x-request-trace-id': FIXED_REQUEST_ID,
+                    'x-from-headers': 'yes'
+                }
+            }).reply(200, 'ok');
+            const userHeaders = new Headers();
+            userHeaders.set('X-From-Headers', 'yes');
+            const response = await fetch(`${MOCK_ORIGIN}/with-headers-instance`, {
+                headers: userHeaders
+            });
+            expect(response.status).toBe(200);
+            const { request } = loggerMock.logRequest.mock.calls[0][0];
+            expect(request.headers.get('x-request-trace-id')).toBe(FIXED_REQUEST_ID);
+            expect(request.headers.get('x-from-headers')).toBe('yes');
+        });
+        it('calls logFailure when the mock responds with replyWithError', async () => {
+            undiciCtx.mockAgent.get(MOCK_ORIGIN).intercept({ path: '/boom', method: 'GET' }).replyWithError(new Error('simulated network failure'));
+            await expect(fetch(`${MOCK_ORIGIN}/boom`)).rejects.toThrow('fetch failed');
+            expect(loggerMock.logRequest).toHaveBeenCalledTimes(1);
+            expect(loggerMock.logResponse).not.toHaveBeenCalled();
+            expect(loggerMock.logFailure).toHaveBeenCalledTimes(1);
+            expect(loggerMock.logFailure.mock.calls[0][0].requestId).toBe(FIXED_REQUEST_ID);
+            const failure = loggerMock.logFailure.mock.calls[0][0].error;
+            expect(failure).toBeInstanceOf(TypeError);
+            expect(failure.message).toBe('fetch failed');
+            expect(failure.cause).toBeInstanceOf(Error);
+            expect(failure.cause.message).toBe('simulated network failure');
+        });
+        it('fails when no mock matches (disabled net)', async () => {
+            await expect(fetch(`${MOCK_ORIGIN}/unmocked`)).rejects.toThrow();
+            expect(loggerMock.logRequest).toHaveBeenCalledTimes(1);
+            expect(loggerMock.logResponse).not.toHaveBeenCalled();
+            expect(loggerMock.logFailure).toHaveBeenCalledTimes(1);
+            expect(utilsMock.addRequestIdToResponse).not.toHaveBeenCalled();
+        });
+        it('passes method and body through to undici for POST JSON', async () => {
+            undiciCtx.mockAgent.get(MOCK_ORIGIN).intercept({ path: '/create', method: 'POST' }).reply(201, JSON.stringify({ id: 1 }), { headers: { 'content-type': 'application/json' } });
+            const response = await fetch(`${MOCK_ORIGIN}/create`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ name: 'a' })
+            });
+            expect(response.status).toBe(201);
+            expect(loggerMock.logRequest.mock.calls[0][0].request.method).toBe('POST');
+            expect(loggerMock.logResponse).toHaveBeenCalledTimes(1);
+        });
+        it('works when the second argument is omitted', async () => {
+            undiciCtx.mockAgent.get(MOCK_ORIGIN).intercept({ path: '/bare', method: 'GET' }).reply(204);
+            const response = await fetch(`${MOCK_ORIGIN}/bare`);
+            expect(response.status).toBe(204);
+            expect(loggerMock.logRequest.mock.calls[0][0].request.method).toBe('GET');
+        });
+    });
+    describe('fetch RequestInfo / RequestInit shapes', () => {
+        it('accepts a URL object as the first argument', async () => {
+            undiciCtx.mockAgent.get(MOCK_ORIGIN).intercept({ path: '/from-url', method: 'GET' }).reply(200, 'url-ok', { headers: { 'content-type': 'text/plain' } });
+            const href = new URL('/from-url', `${MOCK_ORIGIN}/`);
+            const response = await fetch(href);
+            expect(response.status).toBe(200);
+            expect(await response.text()).toBe('url-ok');
+            expect(loggerMock.logRequest.mock.calls[0][0].request.url).toBe(href.href);
+        });
+        it('accepts a Request as the first argument (no init)', async () => {
+            undiciCtx.mockAgent.get(MOCK_ORIGIN).intercept({ path: '/req-only', method: 'GET' }).reply(200, 'r1');
+            const input = new Request(`${MOCK_ORIGIN}/req-only`, { method: 'GET' });
+            const response = await fetch(input);
+            expect(response.status).toBe(200);
+            expect(await response.text()).toBe('r1');
+            const { request } = loggerMock.logRequest.mock.calls[0][0];
+            expect(request.method).toBe('GET');
+            expect(request.url).toBe(`${MOCK_ORIGIN}/req-only`);
+        });
+        it('accepts Request plus init that overrides method and body', async () => {
+            undiciCtx.mockAgent.get(MOCK_ORIGIN).intercept({ path: '/req-plus-init', method: 'POST' }).reply(201, JSON.stringify({ saved: true }), { headers: { 'content-type': 'application/json' } });
+            const input = new Request(`${MOCK_ORIGIN}/req-plus-init`, { method: 'GET' });
+            const response = await fetch(input, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ name: 'override' })
+            });
+            expect(response.status).toBe(201);
+            expect(loggerMock.logRequest.mock.calls[0][0].request.method).toBe('POST');
+            expect(loggerMock.logResponse).toHaveBeenCalledTimes(1);
+        });
+        it('accepts string URL with explicit undefined init', async () => {
+            undiciCtx.mockAgent.get(MOCK_ORIGIN).intercept({ path: '/explicit-undefined', method: 'GET' }).reply(200, 'ok');
+            const response = await fetch(`${MOCK_ORIGIN}/explicit-undefined`, undefined);
+            expect(response.status).toBe(200);
+            expect(loggerMock.logRequest.mock.calls[0][0].request.method).toBe('GET');
+        });
+        it('accepts URL plus init with method and headers', async () => {
+            undiciCtx.mockAgent.get(MOCK_ORIGIN).intercept({
+                path: '/url-post',
+                method: 'POST',
+                headers: { 'content-type': 'application/json', 'x-request-trace-id': FIXED_REQUEST_ID }
+            }).reply(200, '{}');
+            const href = new URL('/url-post', `${MOCK_ORIGIN}/`);
+            const response = await fetch(href, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: '{}'
+            });
+            expect(response.status).toBe(200);
+            expect(loggerMock.logRequest.mock.calls[0][0].request.method).toBe('POST');
+        });
+    });
+});

package/dist/fetch/logger.d.ts

@@ -0,0 +1,45 @@
+import type { Request, Response } from 'undici';
+/**
+ * Sends the trace start event for an http request
+ *
+ * @param options
+ * @param options.requestId - id of the request
+ * @param options.request - The HTTP Request object
+ */
+export declare const logRequest: ({ requestId, request }: {
+    requestId: string;
+    request: Request;
+}) => Promise<void>;
+/**
+ * Sends the trace error event for an http response with error status
+ *
+ * @param options
+ * @param options.requestId - id of the request
+ * @param options.response - The HTTP Response object
+ */
+export declare const logError: ({ requestId, response }: {
+    requestId: string;
+    response: Response;
+}) => Promise<void>;
+/**
+ * Sends the trace end event for an http response
+ *
+ * @param {object} options
+ * @param options.requestId - id of the request
+ * @param {Response} options.response - The HTTP Response object
+ */
+export declare const logResponse: ({ requestId, response }: {
+    requestId: string;
+    response: Response;
+}) => Promise<void>;
+/**
+ * Creates the trace error event for a network/connection failure
+ *
+ * @param options
+ * @param options.requestId - id of the request
+ * @param options.error - The error thrown
+ */
+export declare const logFailure: ({ requestId, error }: {
+    requestId: string;
+    error: Error;
+}) => void;

package/dist/fetch/logger.js

@@ -0,0 +1,57 @@
+import { Tracing } from '@outputai/core/sdk_activity_integration';
+import { config } from '../config.js';
+import { parseBody, redactHeaders, serializeError } from './utils.js';
+/**
+ * Sends the trace start event for an http request
+ *
+ * @param options
+ * @param options.requestId - id of the request
+ * @param options.request - The HTTP Request object
+ */
+export const logRequest = async ({ requestId, request }) => {
+    Tracing.addEventStart({
+        id: requestId, kind: 'http', name: 'request', details: {
+            method: request.method,
+            url: request.url,
+            ...(config.logVerbose && { headers: redactHeaders(request.headers), body: await parseBody(request) })
+        }
+    });
+    Tracing.addEventAttribute({ eventId: requestId, name: 'requestId', value: requestId });
+};
+/**
+ * Sends the trace error event for an http response with error status
+ *
+ * @param options
+ * @param options.requestId - id of the request
+ * @param options.response - The HTTP Response object
+ */
+export const logError = async ({ requestId, response }) => Tracing.addEventError({
+    id: requestId, details: {
+        status: response.status,
+        statusText: response.statusText,
+        headers: redactHeaders(response.headers),
+        body: await parseBody(response)
+    }
+});
+/**
+ * Sends the trace end event for an http response
+ *
+ * @param {object} options
+ * @param options.requestId - id of the request
+ * @param {Response} options.response - The HTTP Response object
+ */
+export const logResponse = async ({ requestId, response }) => Tracing.addEventEnd({
+    id: requestId, details: {
+        status: response.status,
+        statusText: response.statusText,
+        ...(config.logVerbose && { headers: redactHeaders(response.headers), body: await parseBody(response) })
+    }
+});
+/**
+ * Creates the trace error event for a network/connection failure
+ *
+ * @param options
+ * @param options.requestId - id of the request
+ * @param options.error - The error thrown
+ */
+export const logFailure = ({ requestId, error }) => Tracing.addEventError({ id: requestId, details: serializeError(error) });