@toa.io/extensions.exposition 1.0.0-alpha.0 → 1.0.0-alpha.100

package/source/HTTP/index.ts

@@ -1,3 +1,4 @@
 export * from './Server'
 export * from './messages'
 export * from './exceptions'
+export * from './Context'

package/source/HTTP/messages.test.ts

@@ -1,8 +1,14 @@
+import { PassThrough, Readable } from 'node:stream'
+import * as streamConsumers from 'node:stream/consumers'
+import { once } from 'node:events'
 import { generate } from 'randomstring'
 import * as msgpack from 'msgpackr'
-import { read } from './messages'
-import { createRequest } from './Server.fixtures'
+import { multipart, read, type OutgoingMessage } from './messages'
 import { BadRequest, UnsupportedMediaType } from './exceptions'
+import { formats } from './formats'
+import { Timing } from './Timing'
+import type * as http from 'node:http'
+import type { Context } from './Context'
 
 beforeEach(() => {
   jest.clearAllMocks()
@@ -14,8 +20,8 @@ describe('read', () => {
     const headers = { 'content-type': 'application/json' }
     const input = { [generate()]: generate() }
     const json = JSON.stringify(input)
-    const request = createRequest({ path, headers }, json)
-    const output = await read(request)
+    const context = createContext(path, headers, json)
+    const output = await read(context)
 
     expect(output).toStrictEqual(input)
   })
@@ -24,7 +30,7 @@ describe('read', () => {
     const path = generate()
     const headers = { 'content-type': 'application/yaml' }
     const yaml = 'foo: 1'
-    const request = createRequest({ path, headers }, yaml)
+    const request = createContext(path, headers, yaml)
     const value = await read(request)
 
     expect(value).toStrictEqual({ foo: 1 })
@@ -35,7 +41,7 @@ describe('read', () => {
     const headers = { 'content-type': 'application/msgpack' }
     const input = { [generate()]: generate() }
     const msg = msgpack.encode(input)
-    const request = createRequest({ path, headers }, msg)
+    const request = createContext(path, headers, msg)
     const output = await read(request)
 
     expect(output).toStrictEqual(input)
@@ -45,7 +51,7 @@ describe('read', () => {
     const path = generate()
     const headers = { 'content-type': 'text/plain' }
     const input = generate()
-    const request = createRequest({ path, headers }, input)
+    const request = createContext(path, headers, input)
     const output = await read(request)
 
     expect(output).toStrictEqual(input)
@@ -54,7 +60,7 @@ describe('read', () => {
   it('should throw on unsupported request media type', async () => {
     const path = generate()
     const headers = { 'content-type': 'wtf/' + generate() }
-    const request = createRequest({ path, headers })
+    const request = createContext(path, headers)
 
     await expect(read(request)).rejects.toThrow(UnsupportedMediaType)
   })
@@ -63,8 +69,64 @@ describe('read', () => {
     const path = generate()
     const text = '{ "foo": "val... oops '
     const headers = { 'content-type': 'application/json' }
-    const request = createRequest({ path, headers }, text)
+    const request = createContext(path, headers, text)
 
     await expect(read(request)).rejects.toThrow(BadRequest)
   })
+
+  it('should output correct mulitpart format', async () => {
+    const response = new class extends PassThrough {
+      public readonly headers = new Headers()
+
+      public setHeader (key: string, value: string): this {
+        this.headers.set(key, value)
+
+        return this
+      }
+    }()
+
+    const context = { encoder: formats['text/plain'] } as unknown as Context
+    const message = { body: Readable.from(['Hello', 'New', 'World']) } as unknown as OutgoingMessage
+
+    multipart(message, context, response as unknown as http.ServerResponse)
+
+    await once(message.body, 'end')
+
+    const result = await streamConsumers.text(response)
+
+    expect(result).toBe([
+      '--cut',
+      '',
+      'ACK',
+      '--cut',
+      '',
+      'Hello',
+      '--cut',
+      '',
+      'New',
+      '--cut',
+      '',
+      'World',
+      '--cut',
+      '',
+      'FIN',
+      '--cut--'].join('\r\n'))
+  })
 })
+
+export function createContext
+(url: string, headers: Record<string, string> = {}, content: string | Buffer = ''):
+jest.MockedObject<Context> {
+  const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content)
+  const stream = Readable.from(buffer)
+
+  const mock: Partial<Context> = {
+    request: Object.assign(stream, {
+      url,
+      headers
+    }) as unknown as Context['request'],
+    timing: new Timing(false)
+  }
+
+  return mock as unknown as jest.MockedObject<Context>
+}

package/source/HTTP/messages.ts

@@ -1,22 +1,33 @@
-import { type IncomingHttpHeaders } from 'node:http'
 import { Readable } from 'node:stream'
-import { type Request, type Response } from 'express'
-import { buffer } from '@toa.io/streams'
+import { buffer } from 'node:stream/consumers'
+import { console } from 'openspan'
 import { formats } from './formats'
 import { BadRequest, NotAcceptable, UnsupportedMediaType } from './exceptions'
-import type { ParsedQs } from 'qs'
-import type { Format } from './formats'
+import type { Context } from './Context'
+import type * as http from 'node:http'
+
+const server = `Exposition/${require('../../package.json').version}` +
+  ((process.env.TOA_CONTEXT === undefined ? '' : ` ${process.env.TOA_CONTEXT}`) +
+    (process.env.TOA_ENV === undefined ? '' : `/${process.env.TOA_ENV}`))
+
+export async function write
+(context: Context, response: http.ServerResponse, message: OutgoingMessage): Promise<void> {
+  for (const transform of context.pipelines.response)
+    await transform(message)
+
+  response.setHeader('server', server)
+
+  message.headers?.forEach((value, key) => response.setHeader(key, value))
+  context.timing.append(response)
 
-export function write
-(request: IncomingMessage, response: Response, message: OutgoingMessage): void {
   if (message.body instanceof Readable)
-    stream(message, request, response)
+    stream(message, context, response)
   else
-    send(message, request, response)
+    send(message, context, response)
 }
 
-export async function read (request: Request): Promise<any> {
-  const type = request.headers['content-type']
+export async function read (context: Context): Promise<any> {
+  const type = context.request.headers['content-type']
 
   if (type === undefined)
     return undefined
@@ -25,8 +36,7 @@ export async function read (request: Request): Promise<any> {
     throw new UnsupportedMediaType()
 
   const format = formats[type]
-
-  const buf = await buffer(request)
+  const buf = await context.timing.capture('buffer', buffer(context.request))
 
   try {
     return format.decode(buf)
@@ -35,80 +45,90 @@ export async function read (request: Request): Promise<any> {
   }
 }
 
-function send (message: OutgoingMessage, request: IncomingMessage, response: Response): void {
-  if (message.body === undefined) {
+function send
+(message: OutgoingMessage, context: Context, response: http.ServerResponse): void {
+  if (message.body === undefined || message.body === null) {
     response.end()
 
     return
   }
 
-  if (request.encoder === null)
+  if (context.encoder === null)
     throw new NotAcceptable()
 
-  const buf = request.encoder.encode(message.body)
+  const buf = context.encoder.encode(message.body)
 
-  response.set('content-type', request.encoder.type)
-  response.end(buf)
+  response
+    .setHeader('content-type', context.encoder.type)
+    .appendHeader('vary', 'accept')
+    .end(buf)
 }
 
 function stream
-(message: OutgoingMessage, request: IncomingMessage, response: Response): void {
+(message: OutgoingMessage, context: Context, response: http.ServerResponse): void {
   const encoded = message.headers !== undefined && message.headers.has('content-type')
 
   if (encoded)
-    pipe(message, response)
+    message.body.pipe(response)
   else
-    multipart(message, request, response)
+    multipart(message, context, response)
 
-  message.body.on('error', (e: Error) => {
-    console.error(e)
+  message.body.on('error', (exception: Error) => {
+    console.error('Stream error', { path: context.url.pathname, exception })
     response.end()
   })
 }
 
-function pipe (message: OutgoingMessage, response: Response): void {
-  message.headers?.forEach((value, key) => response.set(key, value))
-  message.body.pipe(response)
-}
-
-function multipart (message: OutgoingMessage, request: IncomingMessage, response: Response): void {
-  if (request.encoder === null)
+export function multipart
+(message: OutgoingMessage, context: Context, response: http.ServerResponse): void {
+  if (context.encoder === null)
     throw new NotAcceptable()
 
-  const encoder = request.encoder
+  const encoder = context.encoder
+
+  response.setHeader('content-type', `${encoder.multipart}; boundary=${BOUNDARY}`)
 
-  response.set('content-type', `${encoder.multipart}; boundary=${BOUNDARY}`)
+  response.write(Buffer.concat([
+    CUT,
+    CRLF,
+    encoder.encode('ACK'),
+    CRLF,
+    CUT
+  ]))
 
   message.body
-    .map((part: unknown) => Buffer.concat([CUT, encoder.encode(part)]))
-    .on('end', () => response.end(FINALCUT))
+    .map((part: unknown) => 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)
 }
 
 const BOUNDARY = 'cut'
 const CUT = Buffer.from(`--${BOUNDARY}\r\n`)
+const CRLF = Buffer.from('\r\n')
 const FINALCUT = Buffer.from(`--${BOUNDARY}--`)
 
-export interface IncomingMessage extends Request {
-  method: string
-  path: string
-  url: string
-  headers: IncomingHttpHeaders
-  query: Query
-  parse: <T> () => Promise<T>
-  encoder: Format | null
-}
-
 export interface OutgoingMessage {
   status?: number
   headers?: Headers
   body?: any
 }
 
-export interface Query extends ParsedQs {
+export interface Query {
+  [key: string]: string | number | undefined
+
   id?: string
   criteria?: string
   sort?: string
   omit?: string
   limit?: string
+  version?: number
 }

package/source/Interception.ts

@@ -0,0 +1,24 @@
+import type { Input, Output } from './io'
+
+export class Interception implements Interceptor {
+  private readonly interceptors: Interceptor[]
+
+  public constructor (interceptors: Interceptor[]) {
+    this.interceptors = interceptors
+  }
+
+  public async intercept (input: Input): Promise<Output> {
+    for (const interceptor of this.interceptors) {
+      const output = await interceptor.intercept(input)
+
+      if (output !== null)
+        return output
+    }
+
+    return null
+  }
+}
+
+export interface Interceptor {
+  intercept: (input: Input) => Output | Promise<Output>
+}

package/source/Introspection.ts

@@ -0,0 +1,11 @@
+import type { Remote } from '@toa.io/core'
+
+export interface Introspection {
+  route?: Record<string, Schema>
+  query?: Record<string, Schema>
+  input?: Schema
+  output?: Schema
+  errors?: string[]
+}
+
+export type Schema = Awaited<ReturnType<Remote['explain']>>['input']

package/source/Mapping.ts

@@ -1,51 +1,97 @@
 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 * as core from '@toa.io/core'
 
 export abstract class Mapping {
-  public static create (query?: syntax.Query): Mapping {
-    if (query === undefined || query === null)
-      return new InputMapping()
+  protected readonly query: Query
+  public abstract readonly queryable: boolean
 
-    const q = new Query(query)
+  public constructor (query: Query) {
+    this.query = query
+  }
+
+  public static create (query?: syntax.Query | null): Mapping {
+    const q = new Query(query!)
+
+    return queryable(query)
+      ? new QueryableMapping(q)
+      : new InputMapping(q)
+  }
 
-    return new QueryableMapping(q)
+  public explain (introspection: Introspection): Record<string, Schema> | null {
+    return this.query.explain(introspection)
   }
 
-  public abstract fit (input: any, qs: http.Query, parameters: Parameter[]): core.Request
+  protected assign (input: any, qs: QueryString): void {
+    if (qs.parameters !== null) {
+      if (typeof input !== 'object' || input === null)
+        throw new Error('Input must be an object to embed query parameters')
+
+      Object.assign(input, qs.parameters)
+    }
+  }
+
+  public abstract fit (input: any, query: http.Query, parameters: Parameter[]): core.Request
 }
 
 class QueryableMapping extends Mapping {
-  private readonly query: Query
+  public override readonly queryable = true
 
-  public constructor (query: Query) {
-    super()
+  public fit (input: any, query: http.Query, parameters: Parameter[]): core.Request {
+    const request: core.Request = {}
+    const qs = this.query.fit(query, parameters)
 
-    this.query = query
-  }
+    if (input === undefined && qs.parameters !== null)
+      input = {}
+
+    this.assign(input, qs)
+
+    if (input !== undefined)
+      request.input = input
 
-  public fit (input: any, qs: http.Query, parameters: Parameter[]): core.Request {
-    const query = this.query.fit(qs, parameters)
+    if (qs.query !== null)
+      request.query = qs.query
 
-    return { input, query }
+    return request
   }
 }
 
 class InputMapping extends Mapping {
-  public fit (input: any, _: unknown, parameters: Parameter[]): core.Request {
-    if (input === undefined && parameters.length > 0)
+  public override readonly queryable = false
+
+  public fit (input: any, query: http.Query, parameters: Parameter[]): core.Request {
+    const request: core.Request = {}
+    const qs = this.query.fit(query, parameters)
+
+    if (input === undefined && (parameters.length > 0 || qs.parameters !== null))
       input = {}
 
-    if (typeof input === 'object')
-      this.assign(input, parameters)
+    if (parameters.length > 0) {
+      if (typeof input !== 'object' || input === null)
+        throw new Error('Input must be an object to embed route parameters')
 
-    return { input }
-  }
+      for (const parameter of parameters)
+        input[parameter.name] = parameter.value
+    }
 
-  private assign (input: Record<string, any>, parameters: Parameter[]): void {
-    for (const parameter of parameters)
-      input[parameter.name] = parameter.value
+    this.assign(input, qs)
+
+    if (input !== undefined)
+      request.input = input
+
+    return request
   }
 }
+
+export function queryable (query?: syntax.Query | null): boolean {
+  if (query === undefined || query === null)
+    return false
+
+  const keys = Object.keys(query)
+
+  return !(keys.length === 1 && keys[0] === 'parameters')
+}

package/source/Query.test.ts

@@ -16,7 +16,7 @@ it('should combine request criteria', async () => {
   const instance = new Query(query)
   const result = instance.fit({ criteria: 'qux==4' }, parameters)
 
-  expect(result.criteria).toStrictEqual('(foo==1);(bar==2;baz==3);(qux==4)')
+  expect(result.query!.criteria).toStrictEqual('(bar==2;baz==3);(foo==1);(qux==4)')
 })
 
 it('should set id parameter as query.id', async () => {
@@ -32,6 +32,6 @@ it('should set id parameter as query.id', async () => {
   const instance = new Query(query)
   const result = instance.fit({}, parameters)
 
-  expect(result.criteria).toBeUndefined()
-  expect(result.id).toStrictEqual(id)
+  expect(result.query!.criteria).toBeUndefined()
+  expect(result.query!.id).toStrictEqual(id)
 })