Toa Exposition

Converter from ROA to SOA.

TL;DR

# manifest.toa.yaml

name: dummy
namespace: dummies

exposition:
  /:
    GET: observe

# context.toa.yaml

exposition:
  host: api.example.com

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

See features for more examples.

Overview

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

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':
    host: the.exmaple.com

A shortcut is also available.

exposition:
  host: the.example.com

Context resources

Exposition annotaion can contain resource declaration under the / key.

# context.toa.yaml

exposition:
  host: 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:
  host: the.example.com
  host@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

• Protocol support
• Resource Tree Definition
• Identity authentication
• Access authorization
• BLOBs
• Components and resources
• Caching
• Features