最佳实践

Custom Runtime 说明

最近更新时间:2020-11-16 19:45:55

在云函数(Serverless Cloud Function,SCF)已支持的开发语言及版本的标准运行环境外,为了满足更多个性化开发语言及版本的函数实现,SCF 提供了 Custom Runtime 服务,即可定制化运行环境。通过开放实现自定义函数运行时,支持根据需求使用任意开发语言的任意版本来编写函数,并实现函数调用中的全局操作,如扩展程序的加载,安全插件,监控 agent 等。SCF 与 Custom Runtime 通过 HTTP 协议通信完成事件的响应处理。

Custom Runtime 部署文件说明

bootstrap:Custom Runtime 固定的可执行引导程序文件,由开发者创建同名可执行程序文件,通过自定义语言及版本实现,直接处理或者通过启动其他可执行文件来处理,完成函数运行时的初始化和调用。
函数文件:开发者通过自定义语言及版本开发实现的函数程序文件。
运行时依赖的库文件或可执行文件:根据自定义语言及版本运行时需要,添加相关依赖的库文件或可执行文件。

通过部署包方式发布,文件构成如下:

  • bootstrap(必须)
  • 函数文件(必须)
  • 运行时依赖的库文件或可执行文件(可选)

由于部署包体积限制,运行时依赖的库文件或者可执行文件体积较大时,建议通过部署包绑定层的组合方式发布,文件构成如下:

  • 部署包:
    • bootstrap(必须)
    • 函数文件(必须)
  • 层:
    • 运行时依赖的库文件或可执行文件(可选)
注意:

以上部署文件中的可执行文件发布至 SCF 前请务必设置好文件的可执行权限,并将部署文件打包后通过 zip 包方式直接上传或通过 COS 上传。例如,当您在 Linux 系统中使用 root 账户编译文件,您可以使用 chmod -R 777 your_path 指令更改文件的权限。

Custom Runtime 运行机制

Custom Runtime 将函数的运行时周期分为初始化阶段和调用阶段。初始化阶段只在实例冷启动过程中一次性执行,调用阶段是实例启动之后每次响应事件调用的执行过程。
不同开发语言及版本的启动时间和执行时间会有差异,SCF 针对 Custom Runtime 增加了初始化超时时间配置,与执行超时时间配置一起管理 Custom Runtime 的运行时生命周期。

函数引导加载

SCF 首先检索部署包中的可执行引导文件 boostrap,根据检索结果并进行如下操作:

  • 检索到 bootstrap 文件且可执行,加载执行 boostrap 程序,进入函数初始化阶段。
  • 未检索到 bootstrap 文件或文件不可执行,返回 bootstrap 文件不存在,启动失败。

函数初始化

开始于执行 bootstrap 引导程序文件,开发者可以根据需要在 bootstrap 中自定义实现个性化操作,直接处理或调用其他可执行程序文件来完成初始化操作。以下为建议在初始化阶段完成的基础操作:

  • 设定运行时依赖库的路径及环境变量等。
  • 加载自定义语言及版本依赖的库文件及扩展程序等,如仍有依赖文件需要实时拉取,可下载至 /tmp 目录。
  • 解析函数文件,并执行函数调用前所需的全局操作或初始化程序(如开发工具包客户端 HTTP CLIENT 等初始化、数据库连接池创建等),便于调用阶段复用。
  • 启动安全、监控等插件。
  • 初始化阶段完成后,需要主动调用运行时 API,访问初始化就绪接口 /runtime/init/ready 通知 SCF,Custom Runtime 运行时已完成初始化,进入就绪状态,否则 SCF 会持续等待,直到达到配置的初始化超时时间后,结束 Custom Runtime 并返回初始化超时错误。若重复通知,则会以首次访问时间作为就绪状态时间结点。

日志及异常

  • SCF 将会收集初始化阶段所有标准输出上报至日志。
  • 函数初始化在超时限制内正常执行完成,初始化阶段的日志会与首次调用日志合并返回。如果在初始化超时限制内由于错误异常未能完成执行,则执行结果返回初始化超时错误,写入标准输出的程序错误及异常日志会上报给 SCF,在控制台日志及日志查询中展示。

函数调用

函数调用阶段需要开发者自定义实现事件获取、调用函数及结果的返回,并循环处理这个过程。

  • 长轮询获取事件,开发者通过自定义语言及版本实现 HTTP CLIENT 访问运行时 API 的事件获取接口 /runtime/invocation/next,响应正文包含事件数据,在一次调用内重复访问此接口均返回相同事件数据。
    注意:

    HTTP CLIENT 请勿设置 get 方法的超时。

  • 根据环境变量、响应头中所需信息及事件信息构建函数调用的参数。
  • 推送事件信息等参数数据,调用函数处理程序。
  • 访问运行时 API 响应结果接口 /runtime/invocation/response 推送函数处理结果,首次调用成功为事件终态,SCF 将进行状态锁定,推送后结果不可变更。
  • 如果函数调用阶段出现错误,通过访问运行时 API 调用错误接口 /runtime/invocation/error 推送错误信息,同时本次调用结束,首次调用视为事件终态,SCF 将进行状态锁定,继续推送结果不可变更。
  • 清理释放本次调用结束后不再需要的资源。

日志及异常

  • SCF 将会收集调用阶段所有标准输出上报至日志。
  • SCF 下发事件后,Custom Runtime 较长时间未获取事件,超过函数执行超时限制,SCF 将结束实例并返回等待获取事件超时错误。
  • SCF 下发事件后,Custom Runtime 获取到事件但未在函数执行超时限制内返回执行结果,SCF 将结束实例并返回执行超时错误。

Custom Runtime 运行时 API

Custom Runtime 由开发者使用自定义语言及版本实现,与 SCF 之间的事件下发、处理结果反馈等需要通过标准协议来进行通信。因此 SCF 提供了运行时 API,来满足与 Custom Runtime 生命期中的交互需要。

SCF 内置有以下环境变量:

  • SCF_RUNTIME_API:运行时 API 地址。
  • SCF_RUNTIME_API_PORT:运行时 API 端口。
  • 更多信息请参阅 环境变量

Custom Runtime 可以通过 SCF_RUNTIME_API:SCF_RUNTIME_API_PORT 来访问运行时 API。

路径 方法 说明
/runtime/init/ready post 运行时初始化完成后,调用接口标识进入就绪状态。
/runtime/invocation/next get 获取调用事件。
响应头包含以下信息:
  • request_id:请求 ID,用于标识触发了函数调用的请求。
  • memory_limit_in_mb:函数内存限制,单位为MB。
  • time_limit_in_ms:函数超时时间,单位为毫秒。
响应体包含事件数据,结构参见 触发器事件消息结构汇总
/runtime/invocation/response post 函数处理结果。
在运行时调用函数处理程序后,将来自函数的响应推送到调用响应接口。
/runtime/invocation/error post 函数返回错误推送到调用错误接口,标识本次调用失败。
目录