@toa.io/extensions.origins

Toa Origins

External communications with permissions over supported protocols (HTTP and AMQP).

TL;DR

# manifest.toa.yaml
name: dummy
namespace: dummies

origins:
  docs: http://www.domain.com/docs/
  queues: ~

async function transition (input, object, context) {
  await context.http.docs.example.get() // GET http://www.domain.com/docs/example
  await context.amqp.queues.emit('something_happened', { really: true })

  // direct Aspect invocation
  await context.aspects.http('docs', 'example', { method: 'GET' })
  await context.aspects.http('http://api.example.com', { method: 'GET' })
}

# context.toa.yaml
origins:
  dummies.dummy:
    queues: amqps://amqp.azure.com

HTTP Aspect

Aspect invocation function signature: async (origin: string, rel: string, reuest: fetch.Request): Response

• origin: name of the origin in the manifest
• rel: reference to a resource relative to the origin's value
• request: Request object

Absolute URLs

async (url: string, request: fetch.Request): fetch.Response

Requests to arbitrary URLs can be implemented with overloaded direct Aspect invocation.

By default, requests to arbitrary URLs are not allowed and must be explicitly permitted by setting permissions in the Origins annotation.

// Node.js bridge
async function transition (input, object, context) {
  await context.aspects.http('https://api.domain.com/example', { method: 'POST' })
}

AMQP Aspect

Uses ComQ, thus, provides interface of comq.IO restricted to emit and request methods.

Manifest

origins manifest is a Pointer with origin names as keys. Its values can be overridden by the context annotation. If the value is null, then it must be overriden.

null manifest

To enable the extension for a component that uses arbitrary URLs without any specific origins to declare, the Origins manifest should be set to null.

# manifest.toa.yaml
origins: ~

Context annotation

The origins annotation is a set of Pointers defined for the corresponding components. The values of each pointer override the values defined in the manifest.

# context.toa.yaml
origins:
  dummies.dummy:
    queues: amqps://amqp.azure.com

HTTP URL Permissions

The rules for arbitrary HTTP requests are stored in the http property of the corresponding component as an object. Each key in the rules object is a regular expression that URLs will be tested against, and each value is a permission — either true to allow the URL or false to deny it. In cases where a URL matches multiple rules, denial takes priority.

The null is a special key that represents any URL.

Example

# context.toa.yaml
origins:
  dummies.dummy:
    http:
      /^https?:\/\/api.domain.com/: true
      /^http:\/\/sandbox.domain.com/@staging: true  # `staging` environment
      /.*hackers.*/: false                          # deny
      ~: true                                       # allow any URL

Deployment

Each key of the annotation is deployed as a Pointer with ID following origins-{component}-{origin} with dots replaced by dashes. This means credentials for the declared origins must be deployed as follows:

# context.toa.yaml
origins:
  dummies.dummy:
    queues: amqp://rmq.example.com

$ toa conceal origins-dummies-dummy-queues username=developer password=secret