@toa.io/extensions.exposition 0.23.0-dev.0 → 0.24.0-alpha.0

package/documentation/access.md

@@ -13,9 +13,8 @@
 
 The Authorization is implemented as a set of [RTD Directives](tree.md#directives).
 
-Directives are executed in a predetermined order until one of them grants access to a resource. If
-none of the
-directives grants access, then the Authorization interrupts request processing and responds with an
+Directives are executed in a predetermined order until one of them grants access to a resource.
+If none of the directives grants access, then the Authorization interrupts request processing and responds with an
 authorization error.
 
 > The Authorization directive provider is named `authorization`,

package/documentation/cache.md

@@ -0,0 +1,42 @@
+# Caching
+
+Directive family `cache` implements the
+HTTP [Cache-Control](https://datatracker.ietf.org/doc/html/rfc2616#section-14.9).
+
+## `cache:control`
+
+Sets the value of the `Cache-Control` header
+for [successful responses](https://datatracker.ietf.org/doc/html/rfc2616#section-10.2)
+to [safe HTTP methods](https://developer.mozilla.org/en-US/docs/Glossary/Safe/HTTP).
+
+```yaml
+/:
+  GET:
+    cache:control: max-age=60000
+```
+
+### Implicit modifications
+
+In terms of security, the following implicit modifications are made to the `Cache-Control` header:
+
+- If it contains the `public` directive without `no-cache` and the request is authenticated,
+  the `no-cache` directive is added.
+  This is done to prevent the storage of authentication tokens in shared caches.
+- If it does not contain the `private` directive and the request is authenticated, the `private`
+  directive is added.
+  This is to prevent the storage of private data in shared caches.
+
+## `cache:exact`
+
+Same as `cache:control` without implicit modifications.
+
+```yaml
+/:
+  GET:
+    cache:exact: public, max-age=60000
+```
+
+## References
+
+- HTTP 14.9.1 [What is cacheable](https://datatracker.ietf.org/doc/html/rfc2616#section-14.9.1)
+- See also [features](/extensions/exposition/features/cache.feature)

package/documentation/octets.md

@@ -114,9 +114,9 @@ created: 1698004822358
 optimize: null
 --cut
 error:
-step: resize
-code: TOO_SMALL
-message: Image is too small
+  step: resize
+  code: TOO_SMALL
+  message: Image is too small
 --cut--
 ```
 

package/documentation/tree.md

@@ -124,7 +124,7 @@ Intermediate Nodes must not have Methods as they are unreachable.
 
 ## Directives
 
-RTD Directives are declared using RTD node or Method keys following the `{provider}:{directive}` pattern and can be used
+RTD Directives are declared using RTD node or Method keys following the `{family}:{directive}` pattern and can be used
 to add or modify the behavior of request processing. Directive declarations are applied to the RTD node where they are
 declared and to all nested nodes.
 
@@ -151,10 +151,6 @@ When it is necessary to avoid directive nesting, a Route can be declared adjacen
 In this example, the Route `/posts/:user-id/:post-id/` has only the `authorization:role` directive
 applied.
 
-> Directives can be declared without the `{provider}:` prefix unless there are multiple directives
-> with the same name
-> across different providers.
-
 Another way to avoid nesting is to declare an _isolated_ Node as follows:
 
 ```yaml

package/features/cache.feature

@@ -0,0 +1,160 @@
+Feature: Caching
+
+  Background:
+    Given the `identity.basic` database contains:
+      # developer:secret
+      # user:12345
+      | _id                              | username  | password                                                     |
+      | b70a7dbca6b14a2eaac8a9eb4b2ff4db | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O |
+    Given the `identity.roles` database contains:
+      | _id                              | identity                         | role      |
+      | 775a648d054e4ce1a65f8f17e5b51803 | b70a7dbca6b14a2eaac8a9eb4b2ff4db | developer |
+
+  Scenario: Caching successful response
+    Given the annotation:
+      """yaml
+      /:
+        anonymous: true
+        GET:
+          cache:control: max-age=60000
+          dev:stub: hello
+      """
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      accept: text/plain
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      content-type: text/plain
+      cache-control: max-age=60000
+
+      hello
+      """
+
+  Scenario: Nested cache directives
+    Given the annotation:
+      """yaml
+      /:
+        cache:control: max-age=30000
+        GET:
+          anonymous: true
+          dev:stub: hello
+        /foo:
+          auth:role: developer
+          GET:
+            dev:stub: hello
+        /bar:
+          auth:role: developer
+          cache:control: max-age=60000, public
+          GET:
+            dev:stub: hello
+      """
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      accept: text/plain
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      content-type: text/plain
+      cache-control: max-age=30000
+
+      hello
+      """
+    When the following request is received:
+      """
+      GET /foo/ HTTP/1.1
+      accept: text/plain
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      content-type: text/plain
+      cache-control: private, max-age=30000
+
+      hello
+      """
+    When the following request is received:
+      """
+      GET /bar/ HTTP/1.1
+      accept: text/plain
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      content-type: text/plain
+      cache-control: no-cache, max-age=60000, public
+
+      hello
+      """
+    And the reply does not contain:
+      """
+      cache-control: private, max-age=30000
+      """
+
+  Scenario: Cache-control is not added when request is unsafe
+    Given the annotation:
+      """yaml
+      /:
+        anonymous: true
+        cache:control: max-age=60000
+        POST:
+          dev:stub: hello
+      """
+    When the following request is received:
+      """
+      POST / HTTP/1.1
+      accept: application/yaml
+      """
+    Then the reply does not contain:
+      """
+      cache-control: max-age=60000
+      """
+
+  Scenario: Cache-control is added without implicit modifications
+    Given the annotation:
+      """yaml
+      /:
+        auth:role: developer
+        cache:exact: max-age=60000, public
+        GET:
+          dev:stub: hello
+      """
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      accept: text/plain
+
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      content-type: text/plain
+      cache-control: max-age=60000, public
+
+      hello
+      """
+
+  Scenario: Response without caching
+    Given the annotation:
+      """yaml
+      /:
+        anonymous: true
+        GET:
+          dev:stub: hello
+      """
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      accept: text/plain
+      """
+    Then the reply does not contain:
+      """
+      cache-control:
+      """

package/features/steps/HTTP.ts

@@ -4,7 +4,7 @@ import * as http from '@toa.io/http'
 import { trim } from '@toa.io/generic'
 import { buffer } from '@toa.io/streams'
 import { open } from '../../../storages/source/test/util'
-import { Parameters } from './parameters'
+import { Parameters } from './Parameters'
 import { Gateway } from './Gateway'
 
 @binding([Gateway, Parameters])
@@ -85,7 +85,13 @@ export class HTTP {
     const { url, method, headers } = http.parse.request(head)
     const href = new URL(url, this.origin).href
     const body = open(filename)
-    const request = { method, headers, body, duplex: 'half' } as unknown as RequestInit
+
+    const request = {
+      method,
+      headers,
+      body: body as unknown as ReadableStream,
+      duplex: 'half'
+    }
 
     try {
       const response = await fetch(href, request)

package/features/steps/Parameters.ts

@@ -8,8 +8,7 @@ export class Parameters {
   }
 }
 
-setDefaultTimeout(10 * 1000)
-
+setDefaultTimeout(30 * 1000)
 process.env.TOA_DEV = '1'
 
 // { octets: tmp:///exposition-octets }

package/features/steps/Workspace.ts

@@ -1,5 +1,6 @@
 import { join } from 'node:path'
-import { directory } from '@toa.io/filesystem'
+import { tmpdir } from 'node:os'
+import { mkdtemp, copy } from 'fs-extra'
 import * as yaml from '@toa.io/yaml'
 
 export class Workspace {
@@ -10,7 +11,8 @@ export class Workspace {
     const method = descriptor.value
 
     descriptor.value = async function (this: Workspace, ...args: any[]): Promise<any> {
-      if (this.root === devnull) this.root = await directory.temp()
+      if (this.root === devnull) this.root =
+        await mkdtemp(join(tmpdir(), Math.random().toString(36).slice(2)))
 
       return method.apply(this, args)
     }
@@ -23,7 +25,7 @@ export class Workspace {
     const source = join(__dirname, 'components', name)
     const target = join(this.root, name)
 
-    await directory.copy(source, target)
+    await copy(source, target)
 
     if (patch !== undefined)
       await this.patchManifest(target, patch)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/extensions.exposition",
-  "version": "0.23.0-dev.0",
+  "version": "0.24.0-alpha.0",
   "description": "Toa Exposition",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -17,11 +17,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@toa.io/core": "0.23.0-dev.0",
-    "@toa.io/generic": "0.23.0-dev.0",
-    "@toa.io/http": "0.23.0-dev.0",
-    "@toa.io/schemas": "0.23.0-dev.0",
-    "@toa.io/streams": "0.23.0-dev.0",
+    "@toa.io/core": "0.24.0-alpha.0",
+    "@toa.io/generic": "0.24.0-alpha.0",
+    "@toa.io/http": "0.24.0-alpha.0",
+    "@toa.io/schemas": "0.24.0-alpha.0",
+    "@toa.io/streams": "0.24.0-alpha.0",
     "bcryptjs": "2.4.3",
     "cors": "2.8.5",
     "error-value": "0.3.0",
@@ -38,17 +38,20 @@
   },
   "scripts": {
     "test": "jest",
-    "transpile": "rm -rf transpiled && npx tsc && npm run transpile:basic && npm run transpile:tokens",
+    "transpile": "rm -rf transpiled && npx tsc && npm run transpile:basic && npm run transpile:tokens && npm run transpile:roles",
     "transpile:basic": "rm -rf ./components/identity.basic/operations && npx tsc -p ./components/identity.basic",
     "transpile:tokens": "rm -rf ./components/identity.tokens/operations && npx tsc -p ./components/identity.tokens",
+    "transpile:roles": "rm -rf ./components/identity.roles/operations && npx tsc -p ./components/identity.roles",
     "features": "npx cucumber-js"
   },
   "devDependencies": {
-    "@toa.io/extensions.storages": "0.23.0-dev.0",
+    "@toa.io/extensions.storages": "0.24.0-alpha.0",
     "@types/bcryptjs": "2.4.3",
     "@types/cors": "2.8.13",
     "@types/express": "4.17.17",
-    "@types/negotiator": "0.6.1"
+    "@types/fs-extra": "11.0.4",
+    "@types/negotiator": "0.6.1",
+    "fs-extra": "11.1.1"
   },
-  "gitHead": "19d4af8ff3b8a1a8f191644f44113c88de4bb404"
+  "gitHead": "09a88bdf444bc5dba66dbf0005c382f3526f0296"
 }

package/readme.md

@@ -182,4 +182,5 @@ exposition:
 - [Access authorization](documentation/access.md)
 - [BLOBs](documentation/octets.md)
 - [Components and resources](documentation/components.md)
+- [Caching](documentation/cache.md)
 - [Features](features)

package/source/HTTP/Server.test.ts

@@ -97,7 +97,9 @@ describe('result', () => {
   it('should send status code 200 if the result has a value', async () => {
     const req = createRequest()
 
-    server.attach(async (): Promise<OutgoingMessage> => ({ headers: {}, body: generate() }))
+    server.attach(async (): Promise<OutgoingMessage> => ({
+      headers: new Headers(), body: generate()
+    }))
     await use(req)
 
     expect(res.status).toHaveBeenCalledWith(200)
@@ -106,7 +108,7 @@ describe('result', () => {
   it('should send status code 204 if the result has no value', async () => {
     const req = createRequest()
 
-    server.attach(async (): Promise<OutgoingMessage> => ({ headers: {} }))
+    server.attach(async (): Promise<OutgoingMessage> => ({ headers: new Headers() }))
     await use(req)
 
     expect(res.status).toHaveBeenCalledWith(204)
@@ -118,7 +120,7 @@ describe('result', () => {
     const buf = Buffer.from(json)
     const req = createRequest({ headers: { accept: 'application/json' } })
 
-    server.attach(async (): Promise<OutgoingMessage> => ({ headers: {}, body }))
+    server.attach(async (): Promise<OutgoingMessage> => ({ headers: new Headers(), body }))
     await use(req)
 
     expect(res.end).toHaveBeenCalledWith(buf)

package/source/HTTP/Server.ts

@@ -1,3 +1,5 @@
+import fs from 'node:fs'
+import os from 'node:os'
 import express from 'express'
 import cors from 'cors'
 import { Connector } from '@toa.io/core'
@@ -22,8 +24,10 @@ export class Server extends Connector {
     this.debug = debug
   }
 
-  public static create (options: Partial<Properties> = {}): Server {
-    const properties: Properties = Object.assign({}, defaults(), options)
+  public static create (options?: Partial<Properties>): Server {
+    const properties: Properties = options === undefined
+      ? DEFAULTS
+      : { ...DEFAULTS, ...options }
 
     const app = express()
 
@@ -35,7 +39,7 @@ export class Server extends Connector {
   }
 
   public attach (process: Processing): void {
-    this.app.use((request: any, response: Response): void => {
+    this.app.use((request: any, response: Response) => {
       this.extend(request)
         .then(process)
         .then(this.success(request, response))
@@ -84,9 +88,8 @@ export class Server extends Connector {
         else if (message.body === undefined) status = 204
         else status = 200
 
-      response
-        .status(status)
-        .set(message.headers)
+      response.status(status)
+      message.headers?.forEach((value, key) => response.set(key, value))
 
       if (message.body !== undefined && message.body !== null)
         write(request, response, message)
@@ -96,7 +99,10 @@ export class Server extends Connector {
   }
 
   private fail (request: IncomingMessage, response: Response) {
-    return (exception: Error) => {
+    return async (exception: Error) => {
+      if (!request.complete)
+        await adam(request)
+
       const status = exception instanceof Exception
         ? exception.status
         : 500
@@ -113,10 +119,6 @@ export class Server extends Connector {
         write(request, response, { body })
       } else
         response.end()
-
-      // stop accepting request
-      if (!request.complete)
-        request.destroy()
     }
   }
 }
@@ -135,16 +137,26 @@ function negotiate (request: Request): Format | null {
   return mediaType === undefined ? null : formats[mediaType]
 }
 
+// https://github.com/whatwg/fetch/issues/1254
+async function adam (request: Request): Promise<void> {
+  const completed = promex()
+  const devnull = fs.createWriteStream(os.devNull)
+
+  request
+    .on('end', completed.callback)
+    .pipe(devnull)
+
+  return await completed
+}
+
+const DEFAULTS = {
+  methods: new Set<string>(['GET', 'OPTIONS', 'POST', 'PUT', 'PATCH', 'DELETE']),
+  debug: false
+}
+
 interface Properties {
   methods: Set<string>
   debug: boolean
 }
 
-function defaults (): Properties {
-  return {
-    methods: new Set<string>(['GET', 'OPTIONS', 'POST', 'PUT', 'PATCH', 'DELETE']),
-    debug: false
-  }
-}
-
 export type Processing = (input: IncomingMessage) => Promise<OutgoingMessage>

package/source/HTTP/messages.ts

@@ -1,4 +1,4 @@
-import { type IncomingHttpHeaders, type OutgoingHttpHeaders } from 'node:http'
+import { type IncomingHttpHeaders } from 'node:http'
 import { Readable } from 'node:stream'
 import { type Request, type Response } from 'express'
 import { buffer } from '@toa.io/streams'
@@ -53,7 +53,7 @@ function send (message: OutgoingMessage, request: IncomingMessage, response: Res
 
 function stream
 (message: OutgoingMessage, request: IncomingMessage, response: Response): void {
-  const encoded = message.headers !== undefined && 'content-type' in message.headers
+  const encoded = message.headers !== undefined && message.headers.has('content-type')
 
   if (encoded)
     pipe(message, response)
@@ -67,7 +67,7 @@ function stream
 }
 
 function pipe (message: OutgoingMessage, response: Response): void {
-  response.set(message.headers)
+  message.headers?.forEach((value, key) => response.set(key, value))
   message.body.pipe(response)
 }
 
@@ -101,7 +101,7 @@ export interface IncomingMessage extends Request {
 
 export interface OutgoingMessage {
   status?: number
-  headers?: OutgoingHttpHeaders
+  headers?: Headers
   body?: any
 }
 

package/source/RTD/syntax/parse.ts

@@ -5,7 +5,8 @@ import {
   type Route,
   type Method,
   type Mapping,
-  type Directive, type Range
+  type Directive,
+  type Range
 } from './types'
 
 export function parse (input: object, shortcuts?: Shortcuts): Node {

package/source/Tenant.ts

@@ -30,6 +30,11 @@ export class Tenant extends Connector {
       `'${this.branch.namespace}.${this.branch.component}' has started.`)
   }
 
+  public override async dispose (): Promise<void> {
+    console.info('Exposition Tenant for ' +
+      `'${this.branch.namespace}.${this.branch.component}' has been stopped.`)
+  }
+
   private async expose (): Promise<void> {
     await this.broadcast.transmit('expose', this.branch)
   }

package/source/directives/auth/Family.ts

@@ -90,9 +90,9 @@ class Authorization implements Family<Directive, Extension> {
     const authorization = `Token ${token}`
 
     if (response.headers === undefined)
-      response.headers = {}
+      response.headers = new Headers()
 
-    response.headers.authorization = authorization
+    response.headers.set('authorization', authorization)
   }
 
   private async resolve (authorization: string | undefined): Promise<Identity | null> {

package/source/directives/cache/Control.ts

@@ -0,0 +1,59 @@
+import { match } from 'matchacho'
+import type { AuthenticatedRequest, Directive } from './types'
+
+export class Control implements Directive {
+  protected readonly value: string
+  private cache: string | null = null
+
+  public constructor (value: string) {
+    this.value = value
+  }
+
+  public set (request: AuthenticatedRequest, headers: Headers): void {
+    if (!['GET', 'HEAD', 'OPTIONS'].includes(request.method))
+      return
+
+    this.cache ??= this.resolve(request)
+
+    headers.set('cache-control', this.cache)
+  }
+
+  protected resolve (request: AuthenticatedRequest): string {
+    if (request.identity === null)
+      return this.value
+
+    const directives = this.mask()
+
+    if ((directives & (PUBLIC | NO_CACHE)) === PUBLIC)
+      return 'no-cache, ' + this.value
+
+    if ((directives & (PUBLIC | PRIVATE)) === 0)
+      return 'private, ' + this.value
+
+    return this.value
+  }
+
+  private mask (): number {
+    const directives = this.value.match(DIRECTIVES_RX)
+
+    if (directives === null)
+      return 0
+
+    let mask = 0
+
+    for (const directive of directives)
+      mask |= match<number>(directive,
+        'private', PRIVATE,
+        'public', PUBLIC,
+        'no-cache', NO_CACHE,
+        0)
+
+    return mask
+  }
+}
+
+const DIRECTIVES_RX = /\b(private|public|no-cache)\b/ig
+
+const PUBLIC = 1
+const PRIVATE = 2
+const NO_CACHE = 4

package/source/directives/cache/Exact.ts

@@ -0,0 +1,7 @@
+import { Control } from './Control'
+
+export class Exact extends Control {
+  protected override resolve (): string {
+    return this.value
+  }
+}

package/source/directives/cache/Family.ts

@@ -0,0 +1,36 @@
+import { type Input, type Output, type Family } from '../../Directive'
+import { Control } from './Control'
+import { type Directive } from './types'
+import { Exact } from './Exact'
+import type * as http from '../../HTTP'
+
+class Cache implements Family<Directive> {
+  public readonly name: string = 'cache'
+  public readonly mandatory: boolean = false
+
+  public create (name: string, value: any): Directive {
+    const Class = constructors[name]
+
+    if (Class === undefined)
+      throw new Error(`Directive '${name}' is not provided by the '${this.name}' family.`)
+
+    return new Class(value)
+  }
+
+  public preflight (): Output {
+    return null
+  }
+
+  public async settle
+  (directives: Directive[], request: Input, response: http.OutgoingMessage): Promise<void> {
+    response.headers ??= new Headers()
+    directives[0]?.set(request, response.headers)
+  }
+}
+
+const constructors: Record<string, new (value: any) => Directive> = {
+  control: Control,
+  exact: Exact
+}
+
+export = new Cache()

package/source/directives/cache/index.ts

@@ -0,0 +1,3 @@
+import Family from './Family'
+
+export = Family