FaaSlang

1.1函数即服务的语言

以下是最新的FaaSlang规范的工作草案，版本0.3.x，日期为2018年2月12日。

FaaSlang是一个简单的开放规范,用于定义关于FaaS（“无服务器”）函数，网关和客户端接口 （来自任何语言/SDK的请求）的语义和实现细节. 它通过约定文档和接口(如:类型安全机制) 来降低FaaS微服务的结构复杂性. 同样地, GraphQL为接口和嵌套关系(graph)数据提供了意见和规范. FaaSlang为FaaS资源做了同样的事情.

如果你使用FaaSlang‐compliant的部署和API网关 (如:https://stdlib.com). 无服务函数相比于传统网关有如下优点:

• 标准调用约定(HTTP)
• 类型安全
• 强制文档(Enforced Documentation)
• 后台执行(立即响应, worker形式运行)

而这仅仅是个开始。您正在寻找的所有好东西，如速率限制，身份验证等，都不是FaaSlang规范的 一部分，但它们可以轻松的被添加到这个存储库所提供的示例中。

5.1FaaSlang资源定义

一个FaaSlang定义是一个definition.json文件,他应该遵守下面的格式.

给定这样的函数 (文件名 my_function.js):

/**
* This is my function, it likes the greek alphabet
* @param {String} alpha Some letters, I guess
* @param {Number} beta And a number
* @param {Boolean} gamma True or false?
* @returns {Object} some value
*/
module.exports = async function my_function (alpha, beta = 2, gamma, context) {
  /* your code */
};

你应该提供如下的函数定义:

{
  "name": "my_function",
  "format": {
    "language": "nodejs",
    "async": true
  },
  "description": "This is my function, it likes the greek alphabet",
  "bg": {
    "mode": "info",
    "value": ""
  },
  "charge": 1,
  "context": null,
  "params": [
    {
      "name": "alpha",
      "type": "string",
      "description": "Some letters, I guess"
    },
    {
      "name": "beta",
      "type": "number",
      "defaultValue": 2,
      "description": "And a number"
    },
    {
      "name": "gamma",
      "type": "boolean",
      "description": "True or false?"
    }
  ],
  "returns": {
    "type": "object",
    "description": "some value"
  }
}

这个定义是可扩展的,即你可以添加其他字段,但必须遵守这个模式.

定义必须实现下面的字段;

5.2上下文(context)定义

如果函数没有访问上下文(context),它应该始终为null. 如果它是一个对象,则表示函数确实访问了 上下文(context)(即remoteAddresshttp headers等 – 参考 Context).

上下文对象不要求为空,它可以包含特点供应商的详细信息;如 "context": {"user": ["id", "email"]} 可以表明执行上下文指定访问的,已认证用户的id和邮箱地址.

5.3参数

参数具有如下格式;

module.exports = (imageName, callback) => {

  // 获取图片,返回一个buffer
  let png = imageName === 'cat' ?
    fs.readFileSync(`/images/kitty.png`) :
    fs.readFileSync(`/images/no-image.png`);

  // HTTP请求是image/png格式, 默认是buffer,可设置为application/octet-stream
  return callback(null, png, {'Content-Type': 'image/png'});

};

5.4FaaSlang资源请求

FaaSlang‐compliant 请求 必须 完成以下步骤;

1. 确保 资源定义 在存储或加入时有效且符合要求
2. 执行HTTP握手并进行请求信息初始化
3. 接收Array, Object 或进行URL编码的字符串变量
4. 如果存在HTTP和查询参数，则将查询参数用作URL编码变量
5. 如果存在HTTP POST和查询参数,会拒绝指定POST请求体和ClientError
6. 如果通过HTTP POST,请求结果 必须 包含Content-Type标头或立即返回ClientError
7. 如果通过HTTP POST,Content-Type 必须 是application/json格式的Array或Object,或者是application/x-www-form-urlencoded格式的字符串或立即返回ClientError
8. 如果值(通过POST请求体或查询参数获取)是 application/x-www-form-urlencoded格式,将根据类型转换和函数定义信息确定创建Object的类型
9. 如果是Array: 会按顺序检查已定义的params类型一致性的
10. 如果是Object: 会根据params名称检查类型一致性
11. 如果发现存在不一致的地方,停止执行并返回ParameterError
12. 如果参数未设置默认值或未提供参数,将返回ParameterError
13. 如果函数执行时解析失败或无效,则返回FatalError
14. 如果函数达到指定超时(执行时间限制),返回FatalError
15. 如果函数返回错误(使用回调)或者抛出未捕获异常,返回RuntimeError
16. 如果函数返回不一致的响应（与returns类型不匹配），则返回ValueError
17. 如果未遇到任何错误，返回值给客户端
18. 如果通过HTTP并且content-type没有过载(即:指定供应商以指定开发人员的机制),将以application/octet-stream格式返回buffer数据,以application/json格式返回其他数据.

{
  "error": {
    "type": "ClientError",
    "message": "You know nothing, Jon Snow",
    "details": {}
  }
}

{
  "error": {
    "type": "ParameterError",
    "message": "ParameterError",
    "details": {...}
  }
}

{
  "param_name": {
    "message": "((descriptive message stating parameter is required))",
    "required": true
  }
}

{
  "param_name": {
    "message": "((descriptive message stating parameter is invalid))",
    "invalid": true,
    "expected": {
      "type": "number"
    },
    "actual": {
      "type": "string",
      "value": "hello world"
    }
  }
}

{
  "error": {
    "type": "ValueError",
    "message": "ValueError",
    "details": {
      "returns": {
        "message": "((descriptive message stating return value is invalid))",
        "invalid": true,
        "expected": {
          "type": "boolean"
        },
        "actual": {
          "type": "number",
          "value": 2017
        }
      }
    }
  }
}