asecurityteam/serverfull-gateway

Serverfull-Gateway - AWS API Gateway的Serverfull替代方案

概述

本项目是https://github.com/asecurityteam/serverfull%E7%9A%84%E8%A1%A5%E5%85%85%EF%BC%8C%E5%AE%9E%E7%8E%B0%E4%BA%86AWS API Gateway Proxy针对AWS Lambda提供的部分功能。它构建于我们的另一个项目https://github.com/asecurityteam/transportd%E4%B9%8B%E4%B8%8A%EF%BC%8C%E5%90%8E%E8%80%85%E5%B0%86HTTP%E6%80%A7%E8%83%BD%E5%92%8C%E5%BC%B9%E6%80%A7%E5%B7%A5%E5%85%B7%E6%8D%86%E7%BB%91%E4%B8%BA%E4%B8%80%E9%A1%B9%E6%9C%8D%E5%8A%A1%E3%80%82

通常而言，如果有权访问AWS Lambda，建议直接使用AWS Lambda及AWS提供的API Gateway Proxy事件映射功能。本工具较为专业，主要为以下场景设计：

• 希望采用无服务器开发风格，但无法完全访问无服务器/FaaS提供商的团队（如在裸机或私有云基础设施上开发的团队）。
• 准备从AWS Lambda迁移，但不愿重写大量现有代码的团队（如更换云提供商或迁移至EC2以优化运行时性能特性的团队）。

本项目旨在保持较小的功能范围，主要目标包括：

• 通过有效的OpenAPI规范驱动网关、所有路由及输入/输出验证。
• 实现HTTP调用者与Lambda函数之间的适配。
• 提供与AWS API Gateway在请求/响应内容管理及Lambda链接相关功能的合理兼容性。

除transportd已包含的功能外，我们不打算添加超出上述目标的特性。

快速开始

所有功能均由OpenAPI规范驱动。我们使用扩展配置服务器：

yaml
openapi: 3.0.0
# 服务器的通用运行时配置。详情参见transportd文档中的“Runtime Settings”。
x-runtime:
  httpserver:
    address: ":9090"
  logger:
    level: "INFO"
    output: "STDOUT"
  stats:
    output: "DATADOG"
    datadog:
      address: "statsd:8126"
      flushinterval: "10s"
  signals:
    installed:
      - "OS"
    os:
      signals:
        - 2 # SIGINT
        - 15 # SIGTERM
x-transportd:
  backends:
    - app
  app:
    host: "http://app:8080" # Serverfull实例的位置。
    pool:
      ttl: "24h"
      count: 1
info:
  version: 1.0.0
  title: 示例规范
  description: 用于演示
  contact:
    name: 未提供
    email: na@localhost.com
  license:
    name: Apache 2.0
    url: 'https://www.apache.org/licenses/LICENSE-2.0.html'
paths:
  /:
    post:
      x-transportd:
        backend: app
        enabled:
          - lambda # 本项目提供的transportd插件。
        lambda:
          arn: "sample" # Serverfull中配置的lambda名称
          async: false # 异步（即发即弃）或同步（等待响应）
          # 使用Go模板字符串将网关输入映射到lambda输入
          request: '{"value": "#!.Request.Body.inputValue!#"}'
          # 模板字符串也用于将lambda输出映射到网关输出
          success: '{"status": 200, "body": {"v":"#!.Response.Body.someValue!#"}}'
          error: '{"status": 500, "bodyPassthrough": true}'
          # 有关模板详情参见“模板”部分
          authenticate: false # 启用请求的AWS身份验证开关。
          session: # 可选的AWS会话身份验证配置。
            region: "us-west-2" # （若启用身份验证）请求所需的AWS区域。
            sharedprofile: # 可选的配置文件配置。
              file: "" # 留空表示使用AWS默认位置
              profile: "" # 文件中定义的AWS配置文件名称。
            static: # 可选的静态凭证
              id: "" # AWS访问密钥ID。
              secret: "" # AWS密钥。
              token: "" # 可选的临时访问令牌。
            assumerole: # 可选的角色承担凭证。
              role: "" # 要承担的角色ARN。
              externalid: "" # 可选的跨账户角色标识符。
      description: 示例端点。
      requestBody:
        required: true
        description: 请求体。
        application/json:
          schema:
            type: string
      responses:
        "200":
          description: "成功"

配置好OpenAPI文档后，运行：

bash
TRANSPORTD_OPENAPI_SPECIFICATION_FILE="api.yaml" go run main.go

使用Docker镜像

我们提供最新构建的Docker镜像，您可以将规范添加到其中：

dockerfile
FROM atlassian/serverfull-gateway
COPY api.yaml .
ENV TRANSPORTD_OPENAPI_SPECIFICATION_FILE="api.yaml"

基础容器在本项目的Dockerfile中定义，内部使用scratch作为基础镜像。

配置

transportd服务提供了一系列选项，相关文档在该项目中。本项目为transportd添加了一个插件，在每个路径中增加以下选项块：

yaml
lambda:
  arn: "sample" # Serverfull中配置的lambda名称
  async: false # 异步（即发即弃）或同步（等待响应）
  # 使用Go模板字符串将网关输入映射到lambda输入
  request: '{"value": "#!.Request.Body.inputValue!#"}'
  # 模板字符串也用于将lambda输出映射到网关输出
  success: '{"status": 200, "body": {"v":"#!.Response.Body.someValue!#"}}'
  error: '{"status": 500, "bodyPassthrough": true}'

模板

请求模板

Lambda函数仅接收对Invoke API的POST请求体。然而，良好的面向消费者的API会利用OpenAPI规范提供的丰富特性定义输入（如将值放在查询参数或URL段中）。为弥合这一差距，我们提供请求模板配置，将传入的HTTP请求映射为Lambda输入负载。我们使用Go的模板语法（其格式有详细文档）。本项目对模板功能的两个自定义点是：1）模板分隔符；2）注入模板的内容。

由于{和}在JSON中非常常见，我们将其调整为#!（开始）和!#（结束）。这些字符对之间的内容将被解释为模板文本。生成请求模板时，目的是生成可序列化为JSON的结构。注入的结构如下：

json
{
    "Request": {
        "URL": {
            "string": "map[string]string"
        },
        "Query": {
            "string": ["string"]
        },
        "Header": {
            "string": ["string"]
        },
        "Body": {}
    }
}

错误的结构相同，但Body属性实际是AWS错误体，格式为：

json
{
    "errorMessage": "string",
    "errorType": "string",
    "stackTrace": ["string"]
}

而非Lambda的响应。

响应模板

Lambda函数返回的响应码有限，且没有丰富的头信息。为解决这些问题，我们提供对成功和错误响应的模板化能力。成功响应中注入的结构如下：

json
{
    "Request": {
        "URL": {
            "string": "string"
        },
        "Query": {
            "string": ["string"]
        },
        "Header": {
            "string": ["string"]
        },
        "Body": {}
    },
    "Response": {
        "Status": 200,
        "Header": {
            "string": ["string"]
        },
        "Body": {}
    }
}

贡献

许可证

本项目采用Apache 2.0许可证。详见LICENSE.txt。

贡献协议

Atlassian要求签署贡献者协议后才能接受补丁。如果您是个人，可以填写个人CLA。如果您代表公司贡献，请填写企业CLA。