@jr200-labs/xstate-nats 0.9.21 → 0.9.23

package/src/actions/connection.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest'
-import { createActor } from 'xstate'
+import { createActor, waitFor } from 'xstate'
 import { parseNatsResult, connectToNats, disconnectNats } from './connection'
+import { credentialMachine } from '../machines/credentials'
 
 vi.mock('@nats-io/nats-core', async () => {
   const actual = await vi.importActual('@nats-io/nats-core')
@@ -8,6 +9,8 @@ vi.mock('@nats-io/nats-core', async () => {
     ...actual,
     wsconnect: vi.fn(),
     credsAuthenticator: vi.fn((_creds: Uint8Array) => 'mock-authenticator'),
+    usernamePasswordAuthenticator: vi.fn(() => 'mock-userpass-authenticator'),
+    tokenAuthenticator: vi.fn(() => 'mock-token-authenticator'),
   }
 })
 
@@ -44,6 +47,7 @@ describe('parseNatsResult', () => {
 describe('connectToNats', () => {
   beforeEach(() => {
     vi.restoreAllMocks()
+    vi.clearAllMocks()
   })
 
   it('should call wsconnect with opts and no auth', async () => {
@@ -103,8 +107,7 @@ describe('connectToNats', () => {
 
     expect(wsconnect).toHaveBeenCalledWith({
       servers: ['ws://localhost:4222'],
-      user: 'admin',
-      pass: 'secret',
+      authenticator: 'mock-userpass-authenticator',
     })
   })
 
@@ -137,10 +140,64 @@ describe('connectToNats', () => {
 
     expect(wsconnect).toHaveBeenCalledWith({
       servers: ['ws://localhost:4222'],
-      token: 'my-token',
+      authenticator: 'mock-token-authenticator',
     })
   })
 
+  it('uses the latest actor credential for reconnect authentication', async () => {
+    const { wsconnect, usernamePasswordAuthenticator } = await import('@nats-io/nats-core')
+    const expiresAt = Date.now() + 3_600_000
+    const mockConnection = {
+      status: () => ({
+        [Symbol.asyncIterator]: () => ({ next: () => new Promise(() => {}) }),
+      }),
+    }
+    vi.mocked(wsconnect).mockResolvedValue(mockConnection as any)
+    const load = vi
+      .fn()
+      .mockResolvedValueOnce({
+        expiresAt,
+        auth: {
+          type: 'decentralised',
+          sentinelB64: btoa('sentinel'),
+          user: 'user',
+          pass: 'first',
+        },
+      })
+      .mockResolvedValueOnce({
+        expiresAt,
+        auth: {
+          type: 'decentralised',
+          sentinelB64: btoa('sentinel'),
+          user: 'user',
+          pass: 'second',
+        },
+      })
+    const credentialActor = createActor(credentialMachine, {
+      input: { adapter: { load } },
+    }).start()
+    const actor = createActor(connectToNats, {
+      input: {
+        opts: { servers: ['ws://localhost:4222'] },
+        credentialActor,
+      },
+    }).start()
+
+    await waitFor(actor, (snapshot) => snapshot.status === 'done')
+    const password = vi.mocked(usernamePasswordAuthenticator).mock.calls[0][1]
+    expect(typeof password).toBe('function')
+    expect((password as () => string)()).toBe('first')
+
+    credentialActor.send({ type: 'CREDENTIALS.RELOAD' })
+    await vi.waitFor(() => expect(load).toHaveBeenCalledTimes(2))
+    await vi.waitFor(() => expect(credentialActor.getSnapshot().value).toBe('ready'))
+    expect((password as () => string)()).toBe('second')
+    const now = vi.spyOn(Date, 'now').mockReturnValue(expiresAt + 1)
+    expect(() => (password as () => string)()).toThrow('expired')
+    now.mockRestore()
+    credentialActor.stop()
+  })
+
   it('should merge decentralised auth config', async () => {
     const { wsconnect, credsAuthenticator } = await import('@nats-io/nats-core')
     const mockConnection = {
@@ -177,9 +234,7 @@ describe('connectToNats', () => {
     expect(wsconnect).toHaveBeenCalledWith(
       expect.objectContaining({
         servers: ['ws://localhost:4222'],
-        authenticator: 'mock-authenticator',
-        user: 'nkey-user',
-        pass: 'nkey-pass',
+        authenticator: ['mock-authenticator', 'mock-userpass-authenticator'],
       }),
     )
   })

package/src/actions/connection.ts

@@ -5,13 +5,16 @@ import {
   Msg,
   NatsConnection,
   Status,
+  tokenAuthenticator,
+  usernamePasswordAuthenticator,
   wsconnect,
 } from '@nats-io/nats-core'
 import { KvEntry } from '@nats-io/kv'
 import { type AuthConfig } from './types'
 import { withSpan } from '../telemetry'
+import { CredentialActor, getCredentials } from '../machines/credentials'
 
-const makeAuthConfig = (auth?: AuthConfig) => {
+const makeAuthConfig = (auth?: AuthConfig, getLatest?: () => AuthConfig | undefined) => {
   if (!auth) {
     return {}
   }
@@ -19,18 +22,24 @@ const makeAuthConfig = (auth?: AuthConfig) => {
   if (auth.type === 'decentralised') {
     const decodedSentinel = atob(auth!.sentinelB64!)
     return {
-      authenticator: credsAuthenticator(new TextEncoder().encode(decodedSentinel)),
-      user: auth.user,
-      pass: auth.pass,
+      authenticator: [
+        credsAuthenticator(new TextEncoder().encode(decodedSentinel)),
+        usernamePasswordAuthenticator(
+          () => getLatest?.()?.user ?? auth.user!,
+          () => getLatest?.()?.pass ?? auth.pass!,
+        ),
+      ],
     }
   } else if (auth.type === 'userpass') {
     return {
-      user: auth.user,
-      pass: auth.pass,
+      authenticator: usernamePasswordAuthenticator(
+        () => getLatest?.()?.user ?? auth.user!,
+        () => getLatest?.()?.pass ?? auth.pass!,
+      ),
     }
   } else if (auth.type === 'token') {
     return {
-      token: auth.token,
+      authenticator: tokenAuthenticator(() => getLatest?.()?.token ?? auth.token!),
     }
   }
 
@@ -51,12 +60,23 @@ export const connectToNats = fromPromise(
     input: {
       opts: ConnectionOptions
       auth?: AuthConfig
+      credentialActor?: CredentialActor
       onStatus?: (event: InternalStatusEvents) => void
     }
   }): Promise<NatsConnection> => {
+    const credentials = input.credentialActor
+      ? await getCredentials(input.credentialActor)
+      : undefined
+    const auth = credentials?.auth ?? input.auth
     const mergedOpts: ConnectionOptions = {
       ...input.opts,
-      ...makeAuthConfig(input.auth),
+      ...makeAuthConfig(auth, () => {
+        const current = input.credentialActor?.getSnapshot().context.current
+        if (current?.expiresAt !== undefined && current.expiresAt <= Date.now()) {
+          throw new Error('NATS credentials expired')
+        }
+        return current?.auth
+      }),
     }
     const debug = Boolean(mergedOpts.debug)
     const nc = await wsconnect(mergedOpts)

package/src/actions/subject.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { headers, TimeoutError } from '@nats-io/nats-core'
 import { subjectConsolidateState, subjectRequest, subjectPublish } from './subject'
 import type { SubjectSubscriptionConfig } from './subject'
 
@@ -414,6 +415,125 @@ describe('subjectRequest', () => {
     expect(callback).not.toHaveBeenCalled()
   })
 
+  it('reports synchronous connection failures', async () => {
+    const connection = createMockConnection()
+    const requestError = new Error('connection closed')
+    connection.request.mockImplementation(() => {
+      throw requestError
+    })
+    const onRequestResult = vi.fn()
+
+    subjectRequest({
+      input: {
+        connection,
+        subject: 'test.closed',
+        payload: {},
+        callback: vi.fn(),
+        onRequestResult,
+      },
+    })
+
+    await vi.waitFor(() => {
+      expect(onRequestResult).toHaveBeenCalledWith({ ok: false, error: requestError })
+    })
+  })
+
+  it('settles once when the response callback fails', async () => {
+    const connection = createMockConnection()
+    connection.request.mockResolvedValue({ json: () => ({}), string: () => '{}' })
+    const callbackError = new Error('response callback failed')
+    const onRequestResult = vi.fn()
+
+    subjectRequest({
+      input: {
+        connection,
+        subject: 'test.callback-fail',
+        payload: {},
+        callback: () => {
+          throw callbackError
+        },
+        onRequestResult,
+      },
+    })
+
+    await vi.waitFor(() => {
+      expect(onRequestResult).toHaveBeenCalledWith({ ok: false, error: callbackError })
+    })
+    expect(onRequestResult).toHaveBeenCalledTimes(1)
+  })
+
+  it('reports request-header provider failures without sending', async () => {
+    const connection = createMockConnection()
+    const providerError = new Error('token refresh failed')
+    const onRequestResult = vi.fn()
+
+    subjectRequest({
+      input: {
+        connection,
+        subject: 'test.auth-fail',
+        payload: {},
+        callback: vi.fn(),
+        onRequestResult,
+        requestHeaders: () => {
+          throw providerError
+        },
+      },
+    })
+
+    await vi.waitFor(() => {
+      expect(onRequestResult).toHaveBeenCalledWith({ ok: false, error: providerError })
+    })
+    expect(connection.request).not.toHaveBeenCalled()
+  })
+
+  it('uses one timeout for request headers and transport', async () => {
+    const connection = createMockConnection()
+    const onRequestResult = vi.fn()
+
+    subjectRequest({
+      input: {
+        connection,
+        subject: 'test.auth-timeout',
+        payload: {},
+        opts: { timeout: 10 } as any,
+        callback: vi.fn(),
+        onRequestResult,
+        requestHeaders: () => new Promise(() => {}),
+      },
+    })
+
+    await vi.waitFor(() => {
+      expect(onRequestResult).toHaveBeenCalledWith({
+        ok: false,
+        error: expect.any(TimeoutError),
+      })
+    })
+    expect(connection.request).not.toHaveBeenCalled()
+  })
+
+  it('passes only the remaining timeout to transport', async () => {
+    const connection = createMockConnection()
+    connection.request.mockResolvedValue({ json: () => ({}), string: () => '{}' })
+    const requestHeaders = headers()
+    requestHeaders.set('authorization', 'Bearer token')
+    const now = vi.spyOn(performance, 'now').mockReturnValueOnce(100).mockReturnValueOnce(125)
+
+    subjectRequest({
+      input: {
+        connection,
+        subject: 'test.remaining-timeout',
+        payload: {},
+        opts: { timeout: 100 } as any,
+        callback: vi.fn(),
+        requestHeaders: async () => requestHeaders,
+      },
+    })
+
+    await vi.waitFor(() => expect(connection.request).toHaveBeenCalled())
+    expect(connection.request.mock.calls[0][2].timeout).toBe(75)
+    now.mockRestore()
+  })
+
   it('should log request errors for callers without onRequestResult', async () => {
     const connection = createMockConnection()
     connection.request.mockRejectedValue(new Error('request failed'))

package/src/actions/subject.ts

@@ -1,10 +1,13 @@
 import {
+  deadline,
   Msg,
+  MsgHdrs,
   NatsConnection,
   PublishOptions,
   RequestOptions,
   Subscription,
   SubscriptionOptions,
+  TimeoutError,
 } from '@nats-io/nats-core'
 import { parseNatsResult } from './connection'
 import {
@@ -24,6 +27,25 @@ export type SubjectSubscriptionConfig = {
 
 export type RequestResult = { ok: true } | { ok: false; error: Error }
 
+function notifyRequestResult(
+  callback: ((result: RequestResult) => void) | undefined,
+  result: RequestResult,
+) {
+  try {
+    callback?.(result)
+  } catch (error) {
+    console.error('NATS request result callback failed', error)
+  }
+}
+
+export function rejectUnavailableRequest(event: {
+  onRequestResult?: (result: RequestResult) => void
+}) {
+  const error = new Error('NATS connection is not available')
+  notifyRequestResult(event.onRequestResult, { ok: false, error })
+  if (!event.onRequestResult) console.error(error.message)
+}
+
 export const subjectConsolidateState = ({
   input,
 }: {
@@ -122,9 +144,19 @@ export const subjectRequest = ({
     callback: (data: any) => void
     onRequestResult?: (result: RequestResult) => void
     onDownloadBytes?: (bytes: number) => void
+    requestHeaders?: () => Promise<MsgHdrs | undefined>
   }
 }) => {
-  const { connection, subject, payload, opts, callback, onRequestResult, onDownloadBytes } = input
+  const {
+    connection,
+    subject,
+    payload,
+    opts,
+    callback,
+    onRequestResult,
+    onDownloadBytes,
+    requestHeaders,
+  } = input
   if (!connection) {
     throw new Error('NATS connection is not available')
   }
@@ -145,27 +177,55 @@ export const subjectRequest = ({
       // declares `timeout` as required but nats-core only enforces it when
       // opts is provided; cast preserves the "no opts = use conn default"
       // contract.
-      const headers = injectContextIntoHeaders(opts?.headers)
-      const requestOpts = (opts ? { ...opts, headers } : { headers }) as RequestOptions
+      const request = (providedHeaders?: MsgHdrs, timeout = opts?.timeout) => {
+        const headers = injectContextIntoHeaders(opts?.headers)
+        providedHeaders?.keys().forEach((key) => {
+          const value = providedHeaders.get(key)
+          if (value) headers.set(key, value)
+        })
+        const requestOpts = (opts ? { ...opts, headers } : { headers }) as RequestOptions
+        if (timeout !== undefined) requestOpts.timeout = timeout
 
-      return connection
-        .request(subject, payload, requestOpts)
-        .then((msg: Msg) => {
+        try {
+          return connection.request(subject, payload, requestOpts)
+        } catch (error) {
+          return Promise.reject(error)
+        }
+      }
+
+      const timeout = opts?.timeout
+      const startedAt = performance.now()
+      const preparedHeaders = requestHeaders ? Promise.resolve().then(requestHeaders) : undefined
+      const send = preparedHeaders
+        ? (timeout === undefined ? preparedHeaders : deadline(preparedHeaders, timeout)).then(
+            (headers) => {
+              if (timeout === undefined) return request(headers)
+              const remaining = Math.floor(timeout - (performance.now() - startedAt))
+              if (remaining <= 0) throw new TimeoutError()
+              return request(headers, remaining)
+            },
+          )
+        : request()
+
+      const fail = (err: unknown) => {
+        recordError(span, 'xstate.nats.error', err)
+        const error = err instanceof Error ? err : new Error(String(err))
+        notifyRequestResult(onRequestResult, { ok: false, error })
+        if (!onRequestResult) {
+          console.error(`RequestReply error for subject "${subject}"`, err)
+        }
+      }
+
+      return send.then((msg: Msg) => {
+        try {
           onDownloadBytes?.(msg.data?.length ?? 0)
           callback(parseNatsResult(msg))
-          onRequestResult?.({ ok: true })
-        })
-        .catch((err) => {
-          // Record on span manually so we can swallow the rejection here —
-          // the original fire-and-forget API didn't propagate request errors
-          // to callers and changing that now would be a breaking behaviour.
-          recordError(span, 'xstate.nats.error', err)
-          const error = err instanceof Error ? err : new Error(String(err))
-          onRequestResult?.({ ok: false, error })
-          if (!onRequestResult) {
-            console.error(`RequestReply error for subject "${subject}"`, err)
-          }
-        })
+        } catch (error) {
+          fail(error)
+          return
+        }
+        notifyRequestResult(onRequestResult, { ok: true })
+      }, fail)
     },
   )
 }

package/src/index.ts

@@ -12,6 +12,15 @@ export {
 export { KvSubscriptionKey, type KvSubscriptionConfig } from './actions/kv'
 export { parseNatsResult } from './actions/connection'
 export { type AuthConfig } from './actions/types'
+export {
+  credentialMachine,
+  getCredentials,
+  type CredentialActor,
+  type CredentialContext,
+  type NatsCredentialAdapter,
+  type NatsCredentialConfig,
+  type NatsCredentials,
+} from './machines/credentials'
 export {
   byteLength as natsTrafficByteLength,
   createEmptyTrafficMetrics,

package/src/machines/credentials.telemetry.test.ts

@@ -0,0 +1,66 @@
+import { SpanStatusCode } from '@opentelemetry/api'
+import { createActor, waitFor } from 'xstate'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { setupInMemoryTracer, type OtelTestHarness } from '../../test/otel-setup'
+import * as telemetry from '../telemetry'
+import { credentialMachine, getCredentials } from './credentials'
+
+vi.mock('../telemetry', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../telemetry')>()
+  return {
+    ...actual,
+    recordCredentialOperation: vi.fn(actual.recordCredentialOperation),
+    recordCredentialState: vi.fn(actual.recordCredentialState),
+  }
+})
+
+describe('credential telemetry', () => {
+  let harness: OtelTestHarness
+
+  beforeEach(() => {
+    harness = setupInMemoryTracer()
+    vi.mocked(telemetry.recordCredentialOperation).mockClear()
+    vi.mocked(telemetry.recordCredentialState).mockClear()
+  })
+
+  afterEach(() => {
+    harness.teardown()
+    vi.restoreAllMocks()
+  })
+
+  it('records sanitized operation telemetry and diagnostics', async () => {
+    const debug = vi.spyOn(console, 'debug').mockImplementation(() => {})
+    const secret = 'secret-token-value'
+    const actor = createActor(credentialMachine, {
+      input: {
+        diagnostics: true,
+        adapter: {
+          load: async () => {
+            throw new Error(`provider rejected ${secret}`)
+          },
+        },
+      },
+    }).start()
+
+    await expect(getCredentials(actor)).rejects.toThrow(secret)
+    await waitFor(actor, (snapshot) => snapshot.matches('failed'))
+
+    expect(telemetry.recordCredentialOperation).toHaveBeenCalledWith(
+      'load',
+      'error',
+      expect.any(Number),
+    )
+    expect(telemetry.recordCredentialState).toHaveBeenCalledWith('loading')
+    expect(telemetry.recordCredentialState).toHaveBeenCalledWith('failed')
+    expect(JSON.stringify(debug.mock.calls)).not.toContain(secret)
+
+    const span = harness.exporter
+      .getFinishedSpans()
+      .find((candidate) => candidate.name === 'xstate.nats.credentials.load')
+    expect(span?.status.code).toBe(SpanStatusCode.ERROR)
+    expect(
+      JSON.stringify({ status: span?.status, attributes: span?.attributes, events: span?.events }),
+    ).not.toContain(secret)
+    actor.stop()
+  })
+})