# Interfacing

Since the underlying execution strategy for an action can be a command, a HTTP request, or a RPC call, each action MUST provide an interface for it to be executed:

# HTTP

An action MAY use the HTTP protocol to execute it's function.

actions:
  convert:
    http:
      port: 8080
      method: get
      path: /convert

# Platform to Server

In this communication method the Service's HTTP server MUST be already running and waiting for connections. The Platform will make HTTP requests to the server which results in a response body of data which the Platform would handle.

+------------+         +----------+
|            |         |          |
|  Platform  |         |  Server  |
|            |         |          |
+-----+------+         +-----+----+
      |                      |
      |  {"word": "hello"}   |
      | -------------------> |
      |                      |
      |    {"length": 5}     |
      | <------------------- |
      |                      |

# Location of arguments in the HTTP request

All types of HTTP requests will apply arguments based on the specified in of the argument.

The below example shows a GET request with a query and path parameter.

actions:
  fetch_usd:
    arguments:
      units:
        type: int
        in: query
      currency:
        type: string
        in: path
    output:
       type: int
    http:
      port: 8080
      method: get
      path: /fetch_usd/{currency}

Path parameters MUST be specified in the path

$ curl -X GET http://service:8080/fetch_usd/eur?units=100

This next example is a POST where data is passed via the body.

actions:
  fetch_usd:
    arguments:
      units:
        type: int
        in: requestBody
      currency:
        type: string
        in: requestBody
    output:
      type: int
    http:
      contentType: application/json
      method: post
      path: /convert

$ curl -X POST http://service:8080/path -H "Content-Type: application/json" -d '{"currency": "eur", "units": 100}'

# Command

If the container provider is Docker, then docker exec is used:

# Docker Run/Exec

Docker run/exec can be used as an interface for execution and communication. Data is transmitted using standard output. Arguments can be used to pass values to the container.

Sample

actions:
  count:
    format:
      command: ["/app/count.sh"]
    arguments:
      word:
        type: string
    output:
      type: int

$ docker run --rm alpine /app/count.sh '{"word": "hello"}'
5

# Output

• The Service MAY write data to stdout which is considered the result of the operation.
• The Service MUST exit 0 if it performed the operations successfully.

# Fail and Traceback

• If the Service fails to process the request, it MUST exit 1 or exit 2.
• Data written to stdout is ignored when the exit code is greater than 0.
• Data written to stderr SHOULD be traceback details.

# Deterministic Failure

• The Service MAY exit with code 1 if it failed to performed the operation.
• An exit 1 will inform the Platform not to process the command as the failure is deterministic.

# Retry Failure

• The Service MAY exit with code 2 which indicates a failure and the Platform SHOULD retry.

# Data Flow

+----------+               +------------+                                +----------------------+
|          |               |            |                                |                      |
|  Caller  |               |  Platform  |                                |  Interface via Exec  |
|          |               |            |                                |                      |
+----+-----+               +-----+------+                                +----------+-----------+
     |                           |                                                  |
     |    {"word": "hello"}      |                                                  |
     | ------------------------> |                                                  |
     |                           |   docker exec service count '{"word":"hello"}'   |
     |                           |  --------------------------------------------->  |
     |                           |                     5                            |
     |                           |  <---------------------------------------------  |
     |      {"length": 5}        |                                                  |
     | <------------------------ |                                                  |
     |                           |                                                  |

# RPC

The Service MAY communicate via RPC.

The Service MUST define server and framework attributes.

rpc:
  port: 8080
  framework:
    grpc:
      version: 2
      proto:
        path: git@github-server:project/repo.git/path/to/api.proto # Any valid URI path can be used
  client:
    endpoint: service
    port: 8080
    tls: true