@toa.io/extensions.exposition 0.23.0-dev.0 → 1.0.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/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,15 @@ 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
+
+    headers.connection = 'close' // required for interrupted streams
+
+    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": "1.0.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": "1.0.0-alpha.0",
+    "@toa.io/generic": "1.0.0-alpha.0",
+    "@toa.io/http": "1.0.0-alpha.0",
+    "@toa.io/schemas": "1.0.0-alpha.0",
+    "@toa.io/streams": "1.0.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": "1.0.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": "06c64546f6292cc07c52f74b31415101037f7616"
 }

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

@@ -84,9 +84,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)

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

package/source/directives/cache/types.ts

@@ -0,0 +1,9 @@
+import { type Input } from '../../Directive'
+
+export interface Directive {
+  set: (input: Input, headers: Headers) => void
+}
+
+export interface AuthenticatedRequest extends Input {
+  identity?: unknown | null
+}

package/source/directives/index.ts

@@ -1,6 +1,7 @@
 import { type Family } from '../Directive'
 import Dev from './dev'
 import Auth from './auth'
+import Cache from './cache'
 import Octets from './octets'
 
-export const families: Family[] = [Auth, Octets, Dev]
+export const families: Family[] = [Auth, Octets, Dev, Cache]

package/source/directives/octets/Fetch.ts

@@ -48,11 +48,11 @@ export class Fetch implements Directive {
     if (result instanceof Error)
       throw new NotFound()
 
-    const headers = {
+    const headers = new Headers({
       'content-type': result.type,
-      'content-length': result.size,
+      'content-length': result.size.toString(),
       etag: result.checksum
-    }
+    })
 
     return { headers, body: result.stream }
   }