mppx 0.8.14 → 0.8.17

package/src/proxy/Proxy.upstreamError.test.ts

@@ -0,0 +1,364 @@
+import { describe, expect, test, vi } from 'vp/test'
+
+import * as Mppx from '../server/Mppx.js'
+import * as Proxy from './Proxy.js'
+import * as Service from './Service.js'
+
+type CreatePaidProxyParameters = {
+  fetch: typeof globalThis.fetch
+  method?: 'GET' | 'POST' | undefined
+  onPayment?: (() => void) | undefined
+  onProxyError?: Service.UpstreamErrorHandler | undefined
+  onServiceError?: Service.UpstreamErrorHandler | undefined
+  rewriteRequest?: Service.Service['rewriteRequest']
+  rewriteResponse?: Service.Service['rewriteResponse']
+}
+
+function createPaidProxy(parameters: CreatePaidProxyParameters): Proxy.Proxy {
+  const method = parameters.method ?? 'GET'
+  const service = Service.from('api', {
+    baseUrl: 'https://upstream.example',
+    onUpstreamError: parameters.onServiceError,
+    rewriteRequest: parameters.rewriteRequest,
+    routes: {
+      [`${method} /resource`]: createPaidHandler(parameters.onPayment),
+    },
+  })
+  service.rewriteResponse = parameters.rewriteResponse
+  return Proxy.create({
+    fetch: parameters.fetch,
+    onUpstreamError: parameters.onProxyError,
+    services: [service],
+  })
+}
+
+function createPaidHandler(onPayment?: () => void): Service.IntentHandler {
+  return async () => {
+    onPayment?.()
+    return {
+      status: 200,
+      withReceipt<response>(response: response): response {
+        if (!(response instanceof Response)) throw new Mppx.MissingReceiptResponseError()
+        const headers = new Headers(response.headers)
+        headers.set('Payment-Receipt', 'test-receipt')
+        return new Response(response.body, {
+          headers,
+          status: response.status,
+          statusText: response.statusText,
+        }) as response
+      },
+    }
+  }
+}
+
+function paidRequest(init?: RequestInit): Request {
+  const headers = new Headers(init?.headers)
+  headers.set('Authorization', 'Payment test-credential')
+  return new Request('https://proxy.example/api/resource', {
+    ...init,
+    headers,
+  })
+}
+
+describe('onUpstreamError', () => {
+  test('retries upstream without verifying payment again', async () => {
+    const onPayment = vi.fn()
+    const onUpstreamError = vi.fn((context: Service.UpstreamErrorContext) => ({
+      retry: context.attempt < 3,
+    })) as Service.UpstreamErrorHandler
+    let attempts = 0
+    const fetch = vi.fn(async () => {
+      attempts++
+      if (attempts < 3) return new Response('unavailable', { status: 503 })
+      return Response.json({ ok: true })
+    }) as typeof globalThis.fetch
+    const proxy = createPaidProxy({ fetch, onPayment, onServiceError: onUpstreamError })
+
+    const response = await proxy.fetch(paidRequest())
+
+    expect(response.status).toBe(200)
+    expect(response.headers.get('Payment-Receipt')).toBe('test-receipt')
+    expect(await response.json()).toEqual({ ok: true })
+    expect(fetch).toHaveBeenCalledTimes(3)
+    expect(onPayment).toHaveBeenCalledTimes(1)
+    expect(onUpstreamError).toHaveBeenCalledTimes(2)
+    expect(onUpstreamError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        attempt: 1,
+        error: undefined,
+        response: expect.objectContaining({ status: 503 }),
+        service: expect.objectContaining({ id: 'api' }),
+        upstreamPath: '/resource',
+        upstreamRequest: expect.objectContaining({ url: 'https://upstream.example/resource' }),
+      }),
+    )
+  })
+
+  test('uses the proxy handler when the service has no override', async () => {
+    const upstreamError = new Error('connection reset')
+    const onProxyError = vi.fn((context: Service.UpstreamErrorContext) => ({
+      retry: context.attempt < 2,
+    })) as Service.UpstreamErrorHandler
+    let attempts = 0
+    const fetch = vi.fn(async () => {
+      attempts++
+      if (attempts === 1) throw upstreamError
+      return new Response('recovered')
+    }) as typeof globalThis.fetch
+    const proxy = createPaidProxy({ fetch, onProxyError })
+
+    const response = await proxy.fetch(paidRequest())
+
+    expect(response.status).toBe(200)
+    expect(await response.text()).toBe('recovered')
+    expect(response.headers.get('Payment-Receipt')).toBe('test-receipt')
+    expect(onProxyError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        attempt: 1,
+        error: upstreamError,
+        response: undefined,
+      }),
+    )
+  })
+
+  test('prefers the service handler over the proxy default', async () => {
+    const onProxyError = vi.fn(() => ({ retry: true as const }))
+    const onServiceError = vi.fn(() => ({ retry: false as const }))
+    const fetch = vi.fn(
+      async () => new Response('rate limited', { status: 429 }),
+    ) as typeof globalThis.fetch
+    const proxy = createPaidProxy({ fetch, onProxyError, onServiceError })
+
+    const response = await proxy.fetch(paidRequest())
+
+    expect(response.status).toBe(429)
+    expect(response.headers.get('Payment-Receipt')).toBe('test-receipt')
+    expect(fetch).toHaveBeenCalledTimes(1)
+    expect(onServiceError).toHaveBeenCalledTimes(1)
+    expect(onProxyError).not.toHaveBeenCalled()
+  })
+
+  test('returns a handler fallback and attaches a receipt when it succeeds', async () => {
+    const onServiceError = vi.fn(() => ({
+      response: Response.json({ cached: true }),
+      retry: false as const,
+    }))
+    const fetch = vi.fn(
+      async () => new Response('unavailable', { status: 503 }),
+    ) as typeof globalThis.fetch
+    const proxy = createPaidProxy({ fetch, onServiceError })
+
+    const response = await proxy.fetch(paidRequest())
+
+    expect(response.status).toBe(200)
+    expect(response.headers.get('Payment-Receipt')).toBe('test-receipt')
+    expect(await response.json()).toEqual({ cached: true })
+  })
+
+  test('attaches a receipt when an upstream error is returned', async () => {
+    const fetch = vi.fn(
+      async () => new Response('upstream failed', { status: 500 }),
+    ) as typeof globalThis.fetch
+    const proxy = createPaidProxy({ fetch })
+
+    const response = await proxy.fetch(paidRequest())
+
+    expect(response.status).toBe(500)
+    expect(response.headers.get('Payment-Receipt')).toBe('test-receipt')
+    expect(await response.text()).toBe('upstream failed')
+  })
+
+  test('preserves streaming when error recovery is disabled', async () => {
+    const clone = vi.spyOn(Request.prototype, 'clone')
+    const fetch = vi.fn(async (input: URL | RequestInfo, init?: RequestInit) => {
+      expect(await new Request(input, init).text()).toBe('streamed body')
+      return new Response('ok')
+    }) as typeof globalThis.fetch
+    const proxy = Proxy.create({
+      fetch,
+      services: [
+        Service.from('api', {
+          baseUrl: 'https://upstream.example',
+          routes: { 'POST /resource': true },
+        }),
+      ],
+    })
+
+    try {
+      const response = await proxy.fetch(
+        new Request('https://proxy.example/api/resource', {
+          body: 'streamed body',
+          method: 'POST',
+        }),
+      )
+
+      expect(response.status).toBe(200)
+      expect(clone).not.toHaveBeenCalled()
+    } finally {
+      clone.mockRestore()
+    }
+  })
+
+  test('preserves a failed response body read by the handler', async () => {
+    const onServiceError = vi.fn(async ({ response }: Service.UpstreamErrorContext) => {
+      expect(await response?.text()).toBe('upstream failed')
+      return { retry: false as const }
+    })
+    const fetch = vi.fn(
+      async () => new Response('upstream failed', { status: 503 }),
+    ) as typeof globalThis.fetch
+    const proxy = createPaidProxy({ fetch, onServiceError })
+
+    const response = await proxy.fetch(paidRequest())
+
+    expect(response.status).toBe(503)
+    expect(await response.text()).toBe('upstream failed')
+  })
+
+  test('preserves a recovery response derived from the failed body', async () => {
+    const onServiceError = vi.fn(({ response }: Service.UpstreamErrorContext) => ({
+      response: new Response(response?.body, { status: 200 }),
+      retry: false as const,
+    }))
+    const fetch = vi.fn(
+      async () => new Response('recovered body', { status: 503 }),
+    ) as typeof globalThis.fetch
+    const proxy = createPaidProxy({ fetch, onServiceError })
+
+    const response = await proxy.fetch(paidRequest())
+
+    expect(response.status).toBe(200)
+    expect(response.headers.get('Payment-Receipt')).toBe('test-receipt')
+    expect(await response.text()).toBe('recovered body')
+  })
+
+  test('does not block a retry when the handler partially reads the failed body', async () => {
+    const onServiceError = vi.fn(async ({ response }: Service.UpstreamErrorContext) => {
+      await response?.body?.getReader().read()
+      return { retry: true as const }
+    })
+    let attempts = 0
+    const fetch = vi.fn(async () => {
+      attempts++
+      if (attempts > 1) return new Response('recovered')
+      return new Response(
+        new ReadableStream({
+          start(controller) {
+            controller.enqueue(new TextEncoder().encode('partial failure'))
+          },
+        }),
+        { status: 503 },
+      )
+    }) as typeof globalThis.fetch
+    const proxy = createPaidProxy({ fetch, onServiceError })
+
+    const response = await proxy.fetch(paidRequest())
+
+    expect(response.status).toBe(200)
+    expect(await response.text()).toBe('recovered')
+    expect(fetch).toHaveBeenCalledTimes(2)
+  })
+
+  test('does not retry response rewrite failures', async () => {
+    const rewriteError = new Error('invalid upstream response')
+    const onServiceError = vi.fn(() => ({ retry: true as const }))
+    const rewriteResponse = vi.fn(() => {
+      throw rewriteError
+    })
+    const fetch = vi.fn(async () => new Response('created')) as typeof globalThis.fetch
+    const proxy = createPaidProxy({
+      fetch,
+      method: 'POST',
+      onServiceError,
+      rewriteResponse,
+    })
+
+    await expect(
+      proxy.fetch(paidRequest({ body: 'create resource', method: 'POST' })),
+    ).rejects.toBe(rewriteError)
+    expect(fetch).toHaveBeenCalledTimes(1)
+    expect(onServiceError).not.toHaveBeenCalled()
+  })
+
+  test('preserves a POST body across delayed retries', async () => {
+    const bodies: string[] = []
+    const rewriteRequest = vi.fn((request: Request) => request)
+    const onServiceError = vi.fn(() => ({ delay: 1, retry: true as const }))
+    const fetch = vi.fn(async (input: URL | RequestInfo, init?: RequestInit) => {
+      const request = new Request(input, init)
+      bodies.push(await request.text())
+      if (bodies.length === 1) return new Response('rate limited', { status: 429 })
+      return Response.json({ ok: true })
+    }) as typeof globalThis.fetch
+    const proxy = createPaidProxy({
+      fetch,
+      method: 'POST',
+      onServiceError,
+      rewriteRequest,
+    })
+
+    const response = await proxy.fetch(
+      paidRequest({
+        body: JSON.stringify({ prompt: 'hello' }),
+        headers: { 'Content-Type': 'application/json' },
+        method: 'POST',
+      }),
+    )
+
+    expect(response.status).toBe(200)
+    expect(bodies).toEqual(['{"prompt":"hello"}', '{"prompt":"hello"}'])
+    expect(rewriteRequest).toHaveBeenCalledTimes(2)
+    expect(onServiceError).toHaveBeenCalledTimes(1)
+  })
+
+  test('stops a delayed retry when the client aborts', async () => {
+    const controller = new AbortController()
+    let handlerCalled: (() => void) | undefined
+    const called = new Promise<void>((resolve) => {
+      handlerCalled = resolve
+    })
+    const onServiceError: Service.UpstreamErrorHandler = () => {
+      handlerCalled?.()
+      return { delay: 60_000, retry: true }
+    }
+    const fetch = vi.fn(
+      async () => new Response('unavailable', { status: 503 }),
+    ) as typeof globalThis.fetch
+    const proxy = createPaidProxy({ fetch, onServiceError })
+    const response = proxy.fetch(paidRequest({ signal: controller.signal }))
+    const assertion = expect(response).rejects.toThrow('stop retrying')
+
+    await called
+    controller.abort(new Error('stop retrying'))
+
+    await assertion
+    expect(fetch).toHaveBeenCalledTimes(1)
+  })
+
+  test('also recovers free upstream routes without adding a receipt', async () => {
+    const onUpstreamError = vi.fn(() => ({ retry: true as const }))
+    let attempts = 0
+    const fetch = vi.fn(async () => {
+      attempts++
+      if (attempts === 1) return new Response('unavailable', { status: 503 })
+      return new Response('public resource')
+    }) as typeof globalThis.fetch
+    const proxy = Proxy.create({
+      fetch,
+      services: [
+        Service.from('api', {
+          baseUrl: 'https://upstream.example',
+          onUpstreamError,
+          routes: { 'GET /resource': true },
+        }),
+      ],
+    })
+
+    const response = await proxy.fetch(new Request('https://proxy.example/api/resource'))
+
+    expect(response.status).toBe(200)
+    expect(await response.text()).toBe('public resource')
+    expect(response.headers.get('Payment-Receipt')).toBeNull()
+    expect(fetch).toHaveBeenCalledTimes(2)
+  })
+})

package/src/proxy/Service.test.ts

@@ -12,6 +12,17 @@ describe('from', () => {
     expect(service.baseUrl).toBe('https://api.example.com')
   })
 
+  test('behavior: preserves upstream error hook', () => {
+    const onUpstreamError: Service.UpstreamErrorHandler = () => ({ retry: false })
+    const service = Service.from('api', {
+      baseUrl: 'https://api.example.com',
+      onUpstreamError,
+      routes: { 'GET /v1/status': true },
+    })
+
+    expect(service.onUpstreamError).toBe(onUpstreamError)
+  })
+
   test('behavior: bearer sets Authorization header', async () => {
     const service = Service.from('api', {
       baseUrl: 'https://api.example.com',
@@ -123,7 +134,7 @@ describe('paymentOf', () => {
     expect(Service.paymentOf({ pay: handler, options: {} })).toBeNull()
   })
 
-  test('behavior: strips function internals from payment metadata', () => {
+  test('behavior: derives payment metadata from the canonical request', () => {
     const handler = Object.assign(
       async () => ({
         status: 200 as const,
@@ -131,11 +142,18 @@ describe('paymentOf', () => {
       }),
       {
         _internal: {
-          _canonicalRequest: () => ({}),
+          _canonicalRequest: {
+            amount: '1000000',
+            currency: '0xUSDC',
+            recipient: '0x1',
+          },
           _stableBinding: () => ({}),
           amount: '1',
+          asset: 'raw-asset',
           authorize: () => undefined,
+          client: { apiKey: 'secret' },
           decimals: 6,
+          description: 'Generate text',
           defaults: {},
           intent: 'charge',
           name: 'mock',
@@ -151,9 +169,61 @@ describe('paymentOf', () => {
 
     expect(Service.paymentOf(handler as never)).toEqual({
       amount: '1000000',
-      decimals: 6,
+      currency: '0xUSDC',
+      description: 'Generate text',
       intent: 'charge',
       method: 'mock',
+      recipient: '0x1',
+    })
+  })
+
+  test('behavior: derives every explicitly composed payment offer', () => {
+    const handler = Object.assign(
+      async () => ({
+        status: 200 as const,
+        withReceipt: <T>(r: T) => r,
+      }),
+      {
+        _internal: {
+          offers: [
+            {
+              _canonicalRequest: { amount: '1000000', currency: '0xUSDC' },
+              amount: '1',
+              decimals: 6,
+              description: 'USDC',
+              intent: 'charge',
+              name: 'tempo',
+            },
+            {
+              _canonicalRequest: { amount: '2000000', currency: '0xNANOUSD' },
+              amount: '2',
+              decimals: 6,
+              description: 'NANOUSD',
+              intent: 'charge',
+              name: 'tempo',
+            },
+          ],
+        },
+      },
+    )
+
+    expect(Service.paymentOf(handler as never)).toEqual({
+      offers: [
+        {
+          amount: '1000000',
+          currency: '0xUSDC',
+          description: 'USDC',
+          intent: 'charge',
+          method: 'tempo',
+        },
+        {
+          amount: '2000000',
+          currency: '0xNANOUSD',
+          description: 'NANOUSD',
+          intent: 'charge',
+          method: 'tempo',
+        },
+      ],
     })
   })
 })

package/src/proxy/Service.ts

@@ -1,4 +1,4 @@
-import { Value } from 'ox'
+import * as Metadata from '../discovery/internal/Metadata.js'
 
 /** A proxied upstream service with route definitions and optional request/response hooks. */
 export type Service = {
@@ -12,6 +12,8 @@ export type Service = {
   docs?: Docs | undefined
   /** Unique identifier used as the URL prefix (e.g. `'openai'` → `/{id}/...`). */
   id: string
+  /** Handles failed upstream attempts before the proxy returns a response. Retries do not re-verify payment. */
+  onUpstreamError?: UpstreamErrorHandler | undefined
   /** Hook to modify the upstream request before sending (e.g. inject auth headers). */
   rewriteRequest?: ((req: Request, ctx: Context) => Request | Promise<Request>) | undefined
   /** Hook to modify the upstream response before returning to the client. */
@@ -61,13 +63,50 @@ export type Context = {
   upstreamPath: string
 } & EndpointOptions
 
+/** Context passed to an upstream error handler after a failed proxy attempt. */
+export type UpstreamErrorContext = Context & {
+  /** One-based upstream attempt number. */
+  attempt: number
+  /** Error thrown while preparing or sending the request. Undefined for HTTP error responses. */
+  error: unknown | undefined
+  /** Non-2xx upstream response. Undefined when the attempt threw. */
+  response: Response | undefined
+  /** Rewritten request sent to the upstream service. */
+  upstreamRequest: Request
+}
+
+/** Action returned by an upstream error handler. */
+export type UpstreamErrorAction =
+  | {
+      /** Wait this many milliseconds before retrying. */
+      delay?: number | undefined
+      retry: true
+    }
+  | {
+      /** Optional response to return instead of the original failure. */
+      response?: Response | undefined
+      retry: false
+    }
+
+/**
+ * Handles a non-2xx upstream response or thrown request error.
+ *
+ * This hook runs before the response is returned. It cannot observe failures
+ * from a streaming body after response headers have been sent.
+ */
+export type UpstreamErrorHandler<options = unknown> = (
+  context: UpstreamErrorContext & Partial<Omit<options & {}, 'onUpstreamError' | 'routes'>>,
+) => UpstreamErrorAction | Promise<UpstreamErrorAction>
+
 export type From<
   options extends {
     routes: string
   },
 > = {
   routes: EndpointMap<options['routes']>
-} & Omit<options, 'routes'>
+} & Omit<options, 'onUpstreamError' | 'routes'> & {
+    onUpstreamError?: UpstreamErrorHandler<options> | undefined
+  }
 
 /**
  * Creates a service definition.
@@ -92,6 +131,7 @@ export function from<options = unknown>(id: string, config: from.Config<options>
     description: config.description,
     docs: resolveDocs(config),
     id,
+    onUpstreamError: config.onUpstreamError as Service['onUpstreamError'],
     routes: config.routes,
     title: config.title,
     rewriteRequest: config.rewriteRequest
@@ -126,6 +166,8 @@ export declare namespace from {
       | undefined
     /** Shorthand: full request mutation function. Takes priority over `bearer`/`headers`. */
     mutate?: ((req: Request) => Request | Promise<Request>) | undefined
+    /** Handles failed upstream attempts before the proxy returns a response. Retries do not re-verify payment. */
+    onUpstreamError?: UpstreamErrorHandler<options> | undefined
     /** Hook to modify the upstream request. Receives typed per-endpoint options via `ctx`. */
     rewriteRequest?:
       | ((req: Request, ctx: Context & Partial<options & {}>) => Request | Promise<Request>)
@@ -206,31 +248,16 @@ export function getOptions(endpoint: Endpoint): EndpointOptions | undefined {
   return undefined
 }
 
+/** Derives discovery payment metadata from an explicitly priced endpoint handler. */
 export function paymentOf(endpoint: Endpoint): Record<string, unknown> | null {
   if (endpoint === true) return null
   const handler = typeof endpoint === 'function' ? endpoint : endpoint.pay
   if (!('_internal' in handler)) return null
-  const {
-    name,
-    intent,
-    defaults: _,
-    schema: _s,
-    _canonicalRequest,
-    _stableBinding: _sb,
-    authorize: _a,
-    request: _r,
-    respond: _re,
-    stableBinding: _st,
-    transport: _t,
-    verify: _v,
-    ...rest
-  } = handler._internal as Record<string, unknown>
-  const amount = (() => {
-    if (typeof rest.amount === 'string' && typeof rest.decimals === 'number')
-      return String(Value.from(rest.amount, rest.decimals))
-    return rest.amount
-  })()
-  return { intent, method: name, ...rest, ...(amount !== undefined && { amount }) }
+  const metadata = handler._internal as Metadata.Metadata | undefined
+  if (!metadata) return null
+  if (Metadata.isComposed(metadata))
+    return { offers: Metadata.offers(metadata).map(Metadata.paymentOffer) }
+  return Metadata.paymentOffer(metadata)
 }
 
 function resolveDocs(config: from.Config): Docs | undefined {

package/src/proxy/services/anthropic.ts

@@ -26,6 +26,7 @@ export function anthropic(config: anthropic.Config) {
       apiReference: 'https://docs.anthropic.com/en/api/getting-started',
       homepage: 'https://docs.anthropic.com/en/docs/intro-to-claude',
     },
+    onUpstreamError: config.onUpstreamError,
     rewriteRequest(request, ctx) {
       const apiKey = ctx.apiKey ?? config.apiKey
       request.headers.set('x-api-key', apiKey)

package/src/proxy/services/hooks.test-d.ts

@@ -0,0 +1,14 @@
+import { expectTypeOf, test } from 'vp/test'
+
+import { openai } from './openai.js'
+
+test('upstream error hooks preserve service-specific context', () => {
+  openai({
+    apiKey: 'test',
+    onUpstreamError(context) {
+      expectTypeOf(context.apiKey).toEqualTypeOf<string | undefined>()
+      return { retry: false }
+    },
+    routes: { 'POST /v1/chat/completions': true },
+  })
+})

package/src/proxy/services/hooks.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from 'vp/test'
+
+import type * as Service from '../Service.js'
+import { anthropic } from './anthropic.js'
+import { openai } from './openai.js'
+import { stripe } from './stripe.js'
+
+describe('service hooks', () => {
+  const onUpstreamError: Service.UpstreamErrorHandler = () => ({ retry: false })
+
+  test.each([
+    [
+      'openai',
+      () =>
+        openai({
+          apiKey: 'test',
+          onUpstreamError,
+          routes: { 'POST /v1/chat/completions': true },
+        }),
+    ],
+    [
+      'anthropic',
+      () =>
+        anthropic({
+          apiKey: 'test',
+          onUpstreamError,
+          routes: { 'POST /v1/messages': true },
+        }),
+    ],
+    [
+      'stripe',
+      () =>
+        stripe({
+          apiKey: 'test',
+          onUpstreamError,
+          routes: { 'POST /v1/charges': true },
+        }),
+    ],
+  ] as const)('preserves hooks for %s', (_name, createService) => {
+    const service = createService()
+
+    expect(service.onUpstreamError).toBe(onUpstreamError)
+  })
+})

package/src/proxy/services/openai.ts

@@ -27,6 +27,7 @@ export function openai(config: openai.Config) {
       homepage: 'https://platform.openai.com/docs',
       llms: 'https://context7.com/websites/platform_openai/llms.txt',
     },
+    onUpstreamError: config.onUpstreamError,
     rewriteRequest(request, ctx) {
       const apiKey = ctx.apiKey ?? config.apiKey
       request.headers.delete('OpenAI-Organization')

package/src/proxy/services/stripe.ts

@@ -27,6 +27,7 @@ export function stripe(config: stripe.Config) {
       homepage: 'https://docs.stripe.com',
       llms: 'https://docs.stripe.com/llms.txt',
     },
+    onUpstreamError: config.onUpstreamError,
     rewriteRequest(request, ctx) {
       const apiKey = ctx.apiKey ?? config.apiKey
       request.headers.delete('Stripe-Account')