Skip to content

Latest commit

 

History

History

exposition

Folders and files

NameName
Last commit message
Last commit date

parent directory

..

components

components

 
 

documentation

documentation

 
 

features

features

 
 

schemas

schemas

 
 

source

source

 
 

.gitignore

.gitignore

 
 

.npmignore

.npmignore

 
 

cucumber.js

cucumber.js

 
 

package.json

package.json

 
 

readme.md

readme.md

 
 

tsconfig.json

tsconfig.json

 
 

readme.md

Toa Exposition

Converter from ROA to SOA.

TL;DR

# manifest.toa.yaml

name: dummy
namespace: dummies

exposition:
  /:
    GET: observe
# context.toa.yaml

exposition:
  authorities:
    example: api.example.com
GET /dummies/dummy/
Host: api.example.com

See features for more examples.

Overview

Exposition

The Exposition extension includes a Service, which is an HTTP server with ingress and a Tenant. The Service communicates with Tenants to discover their resource declarations and exposes them as HTTP resources. An instance of the Tenant is running within each Composition that has at least one Component with a resource declaration.

Resource tree discovery

During the startup of the Tenant instance, it broadcasts an expose message containing Resource branches of the Components within the Composition. Upon receiving the expose message, instances of the Service (re-)configures corresponding routes for its HTTP server.

During the startup of the Service instance, it broadcasts a ping message. Once an instance of the Tenant receives a ping message, it broadcasts an expose message.

Resource branch

IA3

A Component can specify how to expose its Operations as HTTP resources by declaring a Resource branch using the manifest extension.

# manifest.toa.yaml

extensions:
  '@toa.io/extensions.exposition': ...

Alternatively, a shortcut exposition is available:

# manifest.toa.yaml

exposition: ...

Resource branches are attached to a Tree with a prefix /{namespace}/{name} or /{name} for components within the default namespace.

# manifest.toa.yaml

name: rooms
namespace: messaging

exposition:
  /: ...
  /:user-id: ...
  /:user-id/:room-id: ...

The declaration above will result in exposing the following resources:

/messaging/rooms/
/messaging/rooms/:user-id/
/messaging/rooms/:user-id/:room-id/

Trailing slash is required.

Context annotation

The Exposition annotation declares options for its deployment.

annotations:
  '@toa.io/extensions.exposition':
    authorities:
      example: the.example.com

A shortcut is also available.

exposition:
  authorities:
    example: the.example.com
Option Description
auhorities Mapping of authority identifiers to domain names. See Authorities.
class Ingress class.
annotations Ingress annotations.
debug Output server errors. Default false.
trace Output server timing. Default false.

Context resources

Exposition annotation can contain resource declaration under the / key.

# context.toa.yaml

exposition:
  authorities:
    example: the.example.com
  /:
    /code:
      GET:
        endpoint: development.code.checkout
        type: observation

In the example above, a request GET /code will be mapped to the development.code.checkout operation call. Unlike a component resource branch declaration, properties namespace, component, and type are required.

If component resource branch conflicts with an annotation, the annotation takes precedence.

Example

exposition:
  authorities:
    example: the.example.com
    example@staging: the.example.dev
  class: alb
  debug@staging: true
  annotations:
    alb.ingress.kubernetes.io/scheme: internet-facing
    alb.ingress.kubernetes.io/target-type: ip
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS": 443}]'
  /:
    /foo:
      GET: foo.bar.observe

See Also