README

受到无服务器/ FaaS/ 云函数趋势的启发。

特性

提供一个框架来构建、调用和测试可重用、无状态的、语言无关的函数（Exo 操作）。
使用语言无关的 YAML 格式来定义 Exo 操作的元数据，指定它们的名称、描述、标签以及详细的 input 和 output 架构。
使用 JSON Schema 验证每个请求、响应、输入和输出。
一个 HTTP 端点服务器，用于提供您的 Exo 操作（exo-server）。
一个控制台工具，可帮助您构建、测试和调试您的 Exo 操作。

项目状态

Exo 目前处于实验阶段，一些功能正在建设中。

core-exo-actions

查看 https://github.com/linkorb/core-exo-actions 以获取一系列可重用的通用 Exo 操作库。

进行测试

cp .env.dist .env
edit .env # setup your EXO_ACTIONS path

# List all available actions
bin/exo action

# Inspect a particular action (hello-php)
bin/exo action hello-php -i greeting=Hello -i name=Alice

# Run a particular action (hello-php) with specified input values
bin/exo run hello-php -i greeting=Hello -i name=Alice

# Handle a full JSON request
bin/exo request < request.json # load request from stdin
bin/exo request request.json # load request from file

自定义操作

实现您自己的操作很容易，使用您喜欢的语言，通常只需几行代码。

查看 core-exo-actions 存储库中的 PHP、node.js 和 Bash 中的 "hello world" 示例（支持大多数其他常用语言）。

要在 Exo（CLI、Worker、Server）中使用您的操作，只需将操作路径添加到 EXO_ACTIONS 环境变量中。

请求/响应 JSON

Exo 将 JSON 请求转换为 JSON 响应。

请求

一个请求包含

操作名称：确定要运行哪个操作
一组可选的输入变量（可能是字符串、整数、对象）：作为输入传递给操作
一组可选的输出映射：应用于输出变量

{
    "action": "random-number",
    "input": {
        "min": "100",
        "max": "200"
    },
    "mapping": {
        "result": "surprise"
    }
}

您可以通过以下方式执行此请求（并使用 jq 进行美化打印和着色）

bin/exo request < request.json | jq

响应

{
    "status": "OK",
    "output": {
        "surprise": "123"
    }
}

处理请求

当 Exo 收到请求时，它将

查找操作信息（输入/输出变量）
根据 data/request.schema.json 验证完整请求
根据请求操作的输入 JSON 架构验证输入变量
执行操作
根据请求操作的输出 JSON 架构验证输出变量
可选地应用输出变量映射（重命名）
根据 data/response.schema.json 验证完整响应
返回响应 JSON

响应

示例响应

{
    "status": "OK",
    "output": {
        "sentence": "Hello, Joe"
    }
}

响应包含一个包含 OK 或 ERROR 的 status。

如果操作有任何输出变量，它们将指定在 output 对象中（可选映射应用）

变量（URL、凭据等）

您可以将变量和秘密作为环境变量添加到您的 exo 实例中。确保环境变量以 EXO__VARIABLE__ 为前缀。例如

EXO__VARIABLE__MATTERMOST_URL=https://mattermost.example.com/hooks/xyz123abc

现在您可以在输入变量中使用这些变量

./bin/exo run mattermost-send-message -i url={{MATTERMOST_URL}} -i channel=@alice -i text=Hi

这些变量仅对 Exo 实例可访问，但任何请求都可以引用它们。这使得从客户端应用程序（例如 Camunda）调用操作变得很容易，而无需在客户端代码、流程等中传递硬编码的 URL 和凭据。

Worker

您可以以 Worker 的形式运行 Exo。在这种模式下，Exo 等待请求，执行它们，并返回响应。

要了解请求的位置，您可以指定 Worker 的类型，以及任何 Worker 需要实例化的选项。

目前有 NATS 和 Camunda Worker 可用。将来可以轻松实现 Kafka、Rabbitmq 或其他类型的 Worker。

要运行工作进程，只需运行

bin/exo worker

NATS Worker

Camunda 工作进程需要以下环境变量

EXO__WORKER__TYPE：工作进程实现：Nats
EXO__WORKER__NATS__HOST：NATS 服务器的主机名，例如 nats.example.com
EXO__WORKER__NATS__PORT：NATS 服务器端口号，例如 4222（默认）
EXO__WORKER__NATS__USERNAME：用于认证的用户名，例如 exo
EXO__WORKER__NATS__PASSWORD：用于认证的密码
EXO__WORKER__NATS__SSL__VERIFY_PEER：配置 SSL 上下文 SSL 选项 verify_peer（默认为 true）

现在您可以在 exo:request "主题" 上发布请求。

请注意，工作进程期望负载是表示常规 Exo 请求的 gzip JSON 字符串。

它将使用 NATS 请求/响应机制以表示常规 Exo 响应的 gzip JSON 字符串来响应请求。

要测试，可以使用包含的 nats-request 命令发送请求（通过 STDIN 的 JSON 或通过提供文件名），并在 STDOUT 上接收响应。此命令使用工作进程的 NATS 环境变量来设置与 NATS 服务器的连接。

./bin/console nats-request < request.json # 从 STDIN 加载请求
./bin/console nats-request request.json # 从文件名加载请求

Camunda Worker

Camunda 工作进程需要以下环境变量

EXO__WORKER__TYPE：工作进程实现：Camunda
EXO__WORKER__CAMUNDA__URL：Camunda REST API 的基本 URL，例如 http://127.0.0.1:8888/engine-rest
EXO__WORKER__CAMUNDA__USERNAME：用于认证的用户名，例如 exo
EXO__WORKER__CAMUNDA__PASSWORD：用于认证的密码

建议为 Exo 创建一个专用用户。这样，每个任务都由适当的用户执行，确保 Camunda 权限和日志与 Exo 正确相关。

一旦工作进程运行，现在您可以在流程中创建触发 Exo 动作的 "服务任务"。

在 Camunda 模型器中创建一个 "任务"，并使用扳手将其转换为 "服务任务"。

在属性面板中，将实现设置为 "外部"，并输入一个主题。主题应始终以 exo: 开头，后跟要执行的操作名称。例如：exo:smtp-send。

打开输入/输出选项卡以指定操作输入变量。您可以使用任何流程变量和 Exo 变量。

示例输入

to：joe@example.web
from：Exo bot
subject：Hello world!
body：This is a demo
dsn：smtp://user:pass@mail.example.web

您还可以指定一个名为 EXO__VARIABLES__SMTP_DSN 的环境变量，并将 {{SMTP_DSN}} 作为 dsn 值指定。这样，您就不需要在 BPMN 流程中硬编码 SMTP 详细信息。

您还可以将 ${someProcessVariable} 指定为一个值以注入流程变量。

对于具有输出变量的操作，您可能希望在将其注入流程之前重命名这些变量。例如，如果 get-user-data 操作返回一个 user 对象，您可能希望将其重命名为 customer（以防止覆盖或处理流程中的多个 user 变量）。这可以通过指定输入变量 >user 并将其值设置为 customer 来实现。

报告

您可以配置 Exo 工作进程以通过 HTTP webhook 请求将心跳和请求详情报告给外部系统作为可选操作。

示例配置

EXO_REPORTING_URL=https://my.example.com/reporting/1234567890

Exo 将在适用的 URL 上附加 /heartbeat、/success、/info 等，并作为 URL 查询参数报告详细信息（即 ?message=...）

日志记录

Exo 及其所有命令都支持基于 PSR-3 的日志记录。要将日志记录到文件中，请指定以下环境变量：

EXO_LOG=/var/log/exo.log

在底层，Exo 使用 monolog，这意味着您可以轻松添加它的许多处理器之一来将日志记录到电子邮件、Slack、Graylog、Elastic、syslog 等。

当通过 ./bin/console 运行 Exo 时，您可以传递 -v 参数将日志输出发送到 STDOUT（除了可选的日志文件）。

许可证

MIT。有关详细信息，请参阅许可证文件。

由 LinkORB 工程团队提供

请查看我们在 linkorb.com/engineering 的其他项目。

顺便说一句，我们在招聘！

Git 钩子

在 .hooks 目录下有一些 Git 钩子。您可以随意复制、调整并使用它们。

linkorb / exo

维护者

详细信息