@toa.io/extensions.exposition 1.0.0-alpha.274 → 1.0.0-alpha.277

package/source/HTTP/messages.ts

@@ -1,19 +1,21 @@
+import { readFileSync } from 'node:fs'
 import { Readable } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
 import { createHash } from 'node:crypto'
 import * as contentType from 'content-type'
 import { console } from 'openspan'
-import { formats } from './formats'
-import { BadRequest, NotAcceptable, UnsupportedMediaType } from './exceptions'
-import type { Context } from './Context'
-import type * as http from 'node:http'
+import { type Format, formats } from './formats/index.js'
+import { BadRequest, NotAcceptable, UnsupportedMediaType } from './exceptions.js'
+import type { Context } from './Context.js'
+import type { ServerResponse } from './types.js'
 
-const server = `Exposition/${require('../../package.json').version}` +
+const server = `Exposition/${JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version}` +
   ((process.env.TOA_CONTEXT === undefined ? '' : ` ${process.env.TOA_CONTEXT}`) +
     (process.env.TOA_ENV === undefined ? '' : `/${process.env.TOA_ENV}`))
 
 const pending = new Map<string, PendingStream>()
 
-export async function write (context: Context, response: http.ServerResponse, message: OutgoingMessage): Promise<void> {
+export async function write (context: Context, response: ServerResponse, message: OutgoingMessage): Promise<void> {
   for (const transform of context.pipelines.response)
     await transform(message)
 
@@ -65,7 +67,7 @@ export async function read (context: Context): Promise<any> {
   }
 }
 
-function send (message: OutgoingMessage, context: Context, response: http.ServerResponse): void {
+function send (message: OutgoingMessage, context: Context, response: ServerResponse): void {
   if (message.body === undefined || message.body === null) {
     // a HEAD reply carries no body but must still report the length a GET would
     // have returned, so a length already set by a directive is left alone
@@ -85,11 +87,10 @@ function send (message: OutgoingMessage, context: Context, response: http.Server
   if (message.etag === true && conditional(context, response, buf))
     return
 
-  response
-    .setHeader('content-type', context.encoder.type)
-    .setHeader('content-length', buf.length.toString())
-    .appendHeader('vary', 'accept')
-    .end(buf)
+  response.setHeader('content-type', context.encoder.type)
+  response.setHeader('content-length', buf.length.toString())
+  response.appendHeader('vary', 'accept')
+  response.end(buf)
 }
 
 /**
@@ -98,7 +99,7 @@ function send (message: OutgoingMessage, context: Context, response: http.Server
  * than from a serialization of its own, so it identifies the representation — which is
  * what `vary` says.
  */
-function conditional (context: Context, response: http.ServerResponse, buf: Buffer): boolean {
+function conditional (context: Context, response: ServerResponse, buf: Buffer): boolean {
   const etag = `"${createHash('sha256').update(buf).digest('hex')}"`
 
   response.setHeader('etag', etag)
@@ -106,9 +107,8 @@ function conditional (context: Context, response: http.ServerResponse, buf: Buff
   if (context.request.headers['if-none-match'] !== etag)
     return false
 
-  response
-    .setHeader('content-length', '0')
-    .appendHeader('vary', 'accept')
+  response.setHeader('content-length', '0')
+  response.appendHeader('vary', 'accept')
 
   response.statusCode = 304
   response.end()
@@ -116,24 +116,28 @@ function conditional (context: Context, response: http.ServerResponse, buf: Buff
   return true
 }
 
-function stream (message: OutgoingMessage, context: Context, response: http.ServerResponse): void {
+function stream (message: OutgoingMessage, context: Context, response: ServerResponse): void {
   const encoded = message.headers !== undefined && message.headers.has('content-type')
+  const source: Readable = encoded ? message.body : multipart(message, context, response)
 
-  if (encoded)
-    message.body.pipe(response)
-  else
-    multipart(message, context, response)
-
-  message.body.on('error', (exception: Error) => {
-    console.warn('Message stream error', { path: context.url.pathname, exception })
-    response.end()
-  })
+  // not awaited: a reply that streams is written long after the request is answered, and a
+  // realtime subscription outlives the span the reply was produced in
+  //
+  // `pipeline` carries an error to every stage and destroys them. `pipe` leaves the stages it
+  // built behind, and an `error` on a stream nobody listens to is an uncaught exception.
+  pipeline(source, response)
+    .catch((exception: Error) =>
+      console.warn('Message stream error', { path: context.url.pathname, exception }))
 
   if (context.debug)
     debugStream(context, response)
 }
 
-export function multipart (message: OutgoingMessage, context: Context, response: http.ServerResponse): void {
+/**
+ * Frames an object stream as `multipart/*`: an `ACK` part, the parts themselves, then `FIN`.
+ * The body is a `Readable`; `write` reached here by testing it.
+ */
+export function multipart (message: OutgoingMessage, context: Context, response: ServerResponse): Readable {
   if (context.encoder === null)
     throw new NotAcceptable()
 
@@ -141,27 +145,20 @@ export function multipart (message: OutgoingMessage, context: Context, response:
 
   response.setHeader('content-type', `${encoder.multipart}; boundary=${BOUNDARY}`)
 
-  response.write(Buffer.concat([
-    CUT,
-    CRLF,
-    encoder.encode('ACK'),
-    CRLF,
-    CUT
-  ]))
+  return Readable.from(frames(message.body as Readable, encoder))
+}
+
+async function * frames (body: Readable, encoder: Format): AsyncGenerator<Buffer> {
+  yield Buffer.concat([CUT, CRLF, encoder.encode('ACK'), CRLF, CUT])
 
-  message.body
-    .map((part: unknown) => Buffer.concat([
+  for await (const part of body)
+    yield Buffer.concat([
       CRLF /* indicates no boundary headers */,
       encoder.encode(part),
       CRLF,
-      CUT]))
-    .on('end', () => response.end(Buffer.concat([
-      CRLF,
-      encoder.encode('FIN'),
-      CRLF,
-      FINALCUT
-    ])))
-    .pipe(response)
+      CUT])
+
+  yield Buffer.concat([CRLF, encoder.encode('FIN'), CRLF, FINALCUT])
 }
 
 const BOUNDARY = 'cut'
@@ -173,7 +170,7 @@ const PENDING_DEBUG_INTERVAL = 30000
 
 let pendingInterval: NodeJS.Timeout | null = null
 
-function debugStream (context: Context, response: http.ServerResponse): void {
+function debugStream (context: Context, response: ServerResponse): void {
   const ctx = { method: context.request.method, path: context.url.pathname }
 
   console.debug('Stream opened', ctx)

package/source/HTTP/types.ts

@@ -0,0 +1,39 @@
+import type { Readable, Writable } from 'node:stream'
+import type { OutgoingHttpHeaders } from 'node:http'
+import type { IncomingHttpHeaders } from 'node:http2'
+
+/**
+ * What Exposition requires of a request. Both `http.IncomingMessage` and
+ * `http2.Http2ServerRequest` satisfy it, so the pipeline is written once.
+ */
+export interface IncomingMessage extends Readable {
+  url: string
+  method: string
+  complete: boolean
+  headers: IncomingHeaders
+  socket: { remoteAddress?: string | undefined }
+}
+
+/**
+ * What Exposition requires of a response.
+ *
+ * `setHeader` and `appendHeader` return `void` because `Http2ServerResponse` returns
+ * nothing from them, so neither can be chained.
+ */
+export interface ServerResponse extends Writable {
+  statusCode: number
+  writableEnded: boolean
+  setHeader: (name: string, value: number | string | string[]) => void
+  appendHeader: (name: string, value: string | string[]) => void
+  hasHeader: (name: string) => boolean
+  writeHead: (status: number, headers?: OutgoingHttpHeaders) => ServerResponse
+}
+
+/**
+ * HTTP/2's header map: HTTP/1.1's, plus the pseudo-headers. `:authority` is typed here
+ * so the authority can be read without narrowing at every call site.
+ */
+export type IncomingHeaders = IncomingHttpHeaders
+
+/** `h2c` is cleartext HTTP/2: there is no in-process TLS to negotiate ALPN with. */
+export type Protocol = 'h1' | 'h2c'

package/source/Interception.ts

@@ -1,4 +1,4 @@
-import type { Input, Output } from './io'
+import type { Input, Output } from './io.js'
 
 export class Interception implements Interceptor {
   private readonly interceptors: Interceptor[]

package/source/Mapping.ts

@@ -1,9 +1,9 @@
-import { type Parameter } from './RTD'
-import { Query } from './Query'
-import type { Introspection, Schema } from './Introspection'
-import type { QueryString } from './Query'
-import type * as http from './HTTP'
-import type * as syntax from './RTD/syntax'
+import { type Parameter } from './RTD/index.js'
+import { Query } from './Query.js'
+import type { Introspection, Schema } from './Introspection.js'
+import type { QueryString } from './Query.js'
+import type * as http from './HTTP/index.js'
+import type * as syntax from './RTD/syntax/index.js'
 import type * as core from '@toa.io/core'
 
 export abstract class Mapping {

package/source/Query.test.ts

@@ -1,5 +1,8 @@
-import { Query } from './Query'
-import { type Parameter, type syntax } from './RTD'
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Query } from './Query.js'
+import { type Parameter, type syntax } from './RTD/index.js'
 
 it('should combine request criteria', async () => {
   const query: syntax.Query = {
@@ -16,7 +19,7 @@ it('should combine request criteria', async () => {
   const instance = new Query(query)
   const result = instance.fit({ criteria: 'qux==4' }, parameters)
 
-  expect(result.query!.criteria).toStrictEqual('(bar==2;baz==3);(foo==1);(qux==4)')
+  assert.deepStrictEqual(result.query!.criteria, '(bar==2;baz==3);(foo==1);(qux==4)')
 })
 
 it('should set id parameter as query.id', async () => {
@@ -32,6 +35,6 @@ it('should set id parameter as query.id', async () => {
   const instance = new Query(query)
   const result = instance.fit({}, parameters)
 
-  expect(result.query!.criteria).toBeUndefined()
-  expect(result.query!.id).toStrictEqual(id)
+  assert.strictEqual(result.query!.criteria, undefined)
+  assert.deepStrictEqual(result.query!.id, id)
 })

package/source/Query.ts

@@ -1,10 +1,10 @@
 import assert from 'node:assert'
-import * as http from './HTTP'
-import { type Parameter } from './RTD'
-import * as schemas from './schemas'
-import { queryable } from './Mapping'
-import type { Introspection, Schema } from './Introspection'
-import type * as syntax from './RTD/syntax'
+import * as http from './HTTP/index.js'
+import { type Parameter } from './RTD/index.js'
+import * as schemas from './schemas.js'
+import { queryable } from './Mapping.js'
+import type { Introspection, Schema } from './Introspection.js'
+import type * as syntax from './RTD/syntax/index.js'
 import type * as core from '@toa.io/core'
 
 export class Query {

package/source/RTD/Context.ts

@@ -1,6 +1,6 @@
-import { type DirectiveFactory } from './Directives'
-import { type EndpointsFactory } from './Endpoint'
-import type { Directive } from './syntax'
+import { type DirectiveFactory } from './Directives.js'
+import { type EndpointsFactory } from './Endpoint.js'
+import type { Directive } from './syntax/index.js'
 
 export interface Context<TExtension = any> {
   readonly protected: boolean

package/source/RTD/Directives.ts

@@ -1,7 +1,7 @@
-import type { Parameter } from './Match'
-import type * as syntax from './syntax'
-import type { Context, OutgoingMessage } from '../HTTP'
-import type { Output } from '../io'
+import type { Parameter } from './Match.js'
+import type * as syntax from './syntax/index.js'
+import type { Context, OutgoingMessage } from '../HTTP/index.js'
+import type { Output } from '../io.js'
 
 export interface Directives {
   preflight: (context: Context, parameters: Parameter[]) => Promise<Output>

package/source/RTD/Endpoint.ts

@@ -1,7 +1,7 @@
-import { type Context } from './Context'
-import type * as http from '../HTTP'
-import type * as syntax from './syntax'
-import type * as RTD from './index'
+import { type Context } from './Context.js'
+import type * as http from '../HTTP/index.js'
+import type * as syntax from './syntax/index.js'
+import type * as RTD from './index.js'
 
 export interface Endpoint {
   call: (context: http.Context, parameters: RTD.Parameter[]) => Promise<http.OutgoingMessage>

package/source/RTD/Match.ts

@@ -1,4 +1,4 @@
-import { type Node } from './Node'
+import { type Node } from './Node.js'
 
 export interface Match {
   node: Node

package/source/RTD/Method.ts

@@ -1,6 +1,6 @@
-import type { Parameter } from './Match'
-import type { Endpoint } from './Endpoint'
-import type { Directives } from './Directives'
+import type { Parameter } from './Match.js'
+import type { Endpoint } from './Endpoint.js'
+import type { Directives } from './Directives.js'
 
 export class Method {
   public readonly endpoint: Endpoint | null

package/source/RTD/Node.ts

@@ -1,6 +1,6 @@
-import { type Route } from './Route'
-import { type Methods } from './Method'
-import { type Match, type Parameter } from './Match'
+import { type Route } from './Route.js'
+import { type Methods } from './Method.js'
+import { type Match, type Parameter } from './Match.js'
 
 export class Node {
   public intermediate: boolean

package/source/RTD/Route.ts

@@ -1,6 +1,6 @@
-import { type Segment } from './segment'
-import { type Match, type Parameter } from './Match'
-import type { Node } from './Node'
+import { type Segment } from './segment.js'
+import { type Match, type Parameter } from './Match.js'
+import type { Node } from './Node.js'
 
 export class Route {
   public readonly root: boolean

package/source/RTD/Tree.ts

@@ -1,11 +1,11 @@
-import { branchTTL, createNode } from './factory'
-import { fragment } from './segment'
-import type { Node } from './Node'
-import type { Match } from './Match'
-import type { Context } from './Context'
-import type { DirectiveFactory } from './Directives'
-import type { EndpointsFactory } from './Endpoint'
-import type * as syntax from './syntax'
+import { branchTTL, createNode } from './factory.js'
+import { fragment } from './segment.js'
+import type { Node } from './Node.js'
+import type { Match } from './Match.js'
+import type { Context } from './Context.js'
+import type { DirectiveFactory } from './Directives.js'
+import type { EndpointsFactory } from './Endpoint.js'
+import type * as syntax from './syntax/index.js'
 
 export class Tree {
   private readonly root: syntax.Node

package/source/RTD/expiration.test.ts

@@ -1,7 +1,10 @@
-import { Tree } from './Tree'
-import type { EndpointsFactory } from '../Endpoint'
-import type { DirectiveFactory } from './Directives'
-import type * as syntax from './syntax'
+import { it, mock } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Tree } from './Tree.js'
+import type { EndpointsFactory } from '../Endpoint.js'
+import type { DirectiveFactory } from './Directives.js'
+import type * as syntax from './syntax/index.js'
 
 const endpoints = {} as unknown as EndpointsFactory
 
@@ -11,7 +14,7 @@ const directives = {
     settle: async () => undefined,
     dispose: () => undefined
   }),
-  dispose: jest.fn()
+  dispose: mock.fn()
 } as unknown as DirectiveFactory
 
 const root: syntax.Node = {
@@ -38,41 +41,41 @@ const pots: syntax.Node = {
 it('should extend expiration without rebuilding the branch', () => {
   process.env.__TESTING_EXPOSITION_BRANCH_TTL = '1000'
 
-  const now = jest.spyOn(Date, 'now').mockReturnValue(10_000)
+  const now = mock.method(Date, 'now', () => 10_000)
   const tree = new Tree(root, endpoints, directives)
   const nodes = tree.merge(pots, { namespace: 'default', component: 'pots' })
   const match = tree.match('/pots/')
 
-  expect(match).not.toBeNull()
+  assert.notStrictEqual(match, null)
 
-  now.mockReturnValue(10_900)
+  now.mock.mockImplementation(() => 10_900)
   tree.refresh(nodes)
 
-  now.mockReturnValue(11_500)
+  now.mock.mockImplementation(() => 11_500)
 
   const refreshed = tree.match('/pots/')
 
-  expect(refreshed).not.toBeNull()
-  expect(refreshed?.node).toBe(match?.node)
+  assert.notStrictEqual(refreshed, null)
+  assert.strictEqual(refreshed?.node, match?.node)
 
-  now.mockRestore()
+  now.mock.restore()
   delete process.env.__TESTING_EXPOSITION_BRANCH_TTL
 })
 
 it('should ignore expired nodes during match', () => {
   process.env.__TESTING_EXPOSITION_BRANCH_TTL = '1000'
 
-  const now = jest.spyOn(Date, 'now').mockReturnValue(10_000)
+  const now = mock.method(Date, 'now', () => 10_000)
   const tree = new Tree(root, endpoints, directives)
 
   tree.merge(pots, { namespace: 'default', component: 'pots' })
 
-  expect(tree.match('/pots/')).not.toBeNull()
+  assert.notStrictEqual(tree.match('/pots/'), null)
 
-  now.mockReturnValue(11_000)
+  now.mock.mockImplementation(() => 11_000)
 
-  expect(tree.match('/pots/')).toBeNull()
+  assert.strictEqual(tree.match('/pots/'), null)
 
-  now.mockRestore()
+  now.mock.restore()
   delete process.env.__TESTING_EXPOSITION_BRANCH_TTL
 })

package/source/RTD/factory.ts

@@ -1,10 +1,10 @@
-import { BRANCH_TTL } from '../const'
-import { Node, type Properties } from './Node'
-import { Route } from './Route'
-import { segment } from './segment'
-import { Method, type Methods } from './Method'
-import type { Context } from './Context'
-import type * as syntax from './syntax'
+import { BRANCH_TTL } from '../const.js'
+import { Node, type Properties } from './Node.js'
+import { Route } from './Route.js'
+import { segment } from './segment.js'
+import { Method, type Methods } from './Method.js'
+import type { Context } from './Context.js'
+import type * as syntax from './syntax/index.js'
 
 export function createNode (node: syntax.Node, context: Context): Node {
   if (node.isolated === true)

package/source/RTD/index.ts

@@ -1,8 +1,8 @@
-export * from './Tree'
-export * from './Node'
-export * from './Match'
-export * from './Method'
-export * from './Context'
-export * from './Endpoint'
-export * from './Directives'
-export * as syntax from './syntax'
+export * from './Tree.js'
+export * from './Node.js'
+export * from './Match.js'
+export * from './Method.js'
+export * from './Context.js'
+export * from './Endpoint.js'
+export * from './Directives.js'
+export * as syntax from './syntax/index.js'

package/source/RTD/segment.test.ts

@@ -1,32 +1,35 @@
-import { segment, fragment } from './segment'
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { segment, fragment } from './segment.js'
 
 it('should return segments', async () => {
   const segments = segment('/foo/bar/')
 
-  expect(segments).toHaveLength(2)
-  expect(segments[0].fragment).toBe('foo')
-  expect(segments[1].fragment).toBe('bar')
+  assert.strictEqual(segments.length, 2)
+  assert.strictEqual(segments[0].fragment, 'foo')
+  assert.strictEqual(segments[1].fragment, 'bar')
 })
 
 it('should parse placeholders', async () => {
   const segments = segment('/foo/:id/')
 
-  expect(segments).toHaveLength(2)
-  expect(segments[0].fragment).toBe('foo')
-  expect(segments[1].fragment).toBeNull()
+  assert.strictEqual(segments.length, 2)
+  assert.strictEqual(segments[0].fragment, 'foo')
+  assert.strictEqual(segments[1].fragment, null)
 
   // helping typescript
   if (segments[1].fragment !== null) throw new Error('?')
 
-  expect(segments[1].placeholder).toBe('id')
+  assert.strictEqual(segments[1].placeholder, 'id')
 })
 
 it('should handle root path', async () => {
-  expect(segment('/')).toStrictEqual([])
+  assert.deepStrictEqual(segment('/'), [])
 })
 
 it('should split', async () => {
   const parts = fragment('/foo/bar/')
 
-  expect(parts).toStrictEqual(['foo', 'bar'])
+  assert.deepStrictEqual(parts, ['foo', 'bar'])
 })

package/source/RTD/syntax/index.ts

@@ -1,2 +1,2 @@
-export * from './parse'
-export * from './types'
+export * from './parse.js'
+export * from './types.js'