Rhai 脚本API参考

定制路由器API

本参考文档记录了特定于Rhai定制对于GraphOS路由器和Apollo路由器核心的符号和行为。

入口钩子

您的Rhai脚本的主文件钩子连接到路由器的各个服务的请求处理生命周期。为了这样做，它定义了所需的以下入口钩子的任意组合：

1
fn router_service(service) {}
2
fn supergraph_service(service) {}
3
fn execution_service(service) {}
4
fn subgraph_service(service, subgraph) {}

在每个钩子内部，您定义自定义逻辑以根据需要与当前活动的请求和/或响应进行交互。这通常涉及使用提供的方法的service对象来注册服务回调，如下所示：

main.rhai

1
fn supergraph_service(service) {
2
  let request_callback = |request| {
3
      print("Supergraph service: Client request received");
4
  };
5
  
6
  let response_callback = |response| {
7
      print("Supergraph service: Client response ready to send");
8
  };
9

10
  service.map_request(request_callback);
11
  service.map_response(response_callback);
12
}

记录

如果您的脚本使用Rhai的内置print()函数记录消息，则该消息将以router的“info”级别记录到日志中：

1
print("logged at the info level");

要更精细地控制消息的日志级别，您可以使用以下函数

1
log_error("error-level log message");
2
log_warn("warn-level log message");
3
log_info("info-level log message");
4
log_debug("debug-level log message");
5
log_trace("trace-level log message");

终止客户端请求

您的Rhai脚本可以终止触发它的关联客户端请求。为此，它抛出异常。这向客户端返回一个Internal Server Error，带有500响应代码。

例如

1
fn supergraph_service(service) {
2
    // Define a closure to process our response
3
    let f = |response| {
4
        // Something goes wrong during response processing...
5
        throw "An error occurred setting up the supergraph_service...";
6
    };
7
    // Map our response using our closure
8
    service.map_response(f);
9
}

如果希望对返回给客户端的HTTP状态代码有更多控制，则可以抛出一个对象映射错误，其中包含键：状态和消息。

键必须是数字，消息必须是可以转换为字符串的事物。

例如

1
fn supergraph_service(service) {
2
    // Define a closure to process our response
3
    let f = |response| {
4
        // Something goes wrong during response processing...
5
        throw #{
6
            status: 400,
7
            message: "An error occurred processing the response..."
8
        };
9
    };
10
    // Map our response using our closure
11
    service.map_response(f);
12
}

您还可以throw一个有效的GraphQL响应，它将被反序列化并由router处理。

例如

1
fn supergraph_service(service) {
2
    // Define a closure to process our request
3
    let f = |request| {
4
        // Something goes wrong during request processing...
5
        throw #{
6
            status: 403,
7
            body: #{
8
                errors: [#{
9
                    message: `I have raised a 403`,
10
                    extensions: #{
11
                        code: "ACCESS_DENIED"
12
                    }
13
                }]
14
            }
15
        };
16
    };
17
    // Map our request using our closure
18
    service.map_request(f);
19
}

Rhai在map_request层上抛出时会表现得与ControlFlow::Break相同，这在外部扩展部分中进行了说明。

如果提供的状态码不是有效的HTTP状态码，则将导致500响应码。

定时执行

您的Rhai自定义可以使用全局Router.APOLLO_START常量来计算持续时间。这类似于Unix环境中的Epoch。

1
// Define a closure to process our response
2
// Note: We can't use a closure in this example because we are referencing our global Router during function execution
3
fn process_response(response) {
4
    let start = Router.APOLLO_START.elapsed;
5
    // Do some processing here...
6
    let duration = Router.APOLLO_START.elapsed - start;
7
    print(`response processing took: ${duration}`);
8

9
    // Log out any errors we may have
10
    print(response.body.errors);
11
}
12

13
fn supergraph_service(service) {
14
    const response_callback = Fn("process_response");
15
    service.map_response(response_callback);
16
}

访问SDL

您的Rhai自定义可以使用全局Router.APOLLO_SDL常量来检查supergraph。

1
fn supergraph_service(service) {
2
    print(`${Router.APOLLO_SDL}`);
3
}

访问TraceId

您的Rhai自定义可以使用函数traceid()来检索opentelemetry跟踪ID。如果不存在span，该函数将抛出异常，因此在使用此函数时始终要处理异常。

1
fn supergraph_service(service) {
2
    try {
3
        let id = traceid();
4
        print(`id: ${id}`);
5
    }
6
    catch(err)
7
    {
8
        // log any errors
9
        log_error(`span id error: ${err}`);
10
    }
11
}

URL编码/解码字符串

您的Rhai自定义可以使用函数urlencode()和urldecode()来编码/解码字符串。encode()不会失败，但decode()可能会失败，因此在使用decode()函数时始终要处理异常。

1
fn supergraph_service(service) {
2
    let original = "alice and bob";
3
    let encoded = urlencode(original);
4
    // encoded will be "alice%20and%20bob"
5
    try {
6
        let and_back = urldecode(encoded);
7
        // and_back will be "alice and bob"
8
    }
9
    catch(err)
10
    {
11
        // log any errors
12
        log_error(`urldecode error: ${err}`);
13
    }
14
}

JSON编码/解码字符串

您的Rhai自定义可以使用函数json::encode()和json::decode()将Rhai对象转换为有效的JSON编码字符串或从有效的JSON编码字符串转换为Rhai对象。这两个函数都可能会失败，因此在使用它们时始终要处理异常。

1
fn router_service(service) {
2
    let original = `{"valid":"object"}`;
3
    try {
4
        let encoded = json::decode(original);
5
        // encoded is a Rhai object, with a property (or key) named valid with a String value of "object"
6
        print(`encoded.valid: ${encoded.valid}`);
7
        let and_back = json::encode(encoded);
8
        // and_back will be a string == original.
9
        if and_back != original {
10
            throw "something has gone wrong";
11
        }
12
    }
13
    catch(err)
14
    {
15
        // log any errors
16
        log_error(`json coding error: ${err}`);
17
    }
18
}

Base64编码/解码字符串

您的Rhai自定义可以使用函数base64::encode()和base64::decode()来编码/解码字符串。encode()不会失败，但decode()可能会失败，因此在使用decode()函数时始终要处理异常。

1
fn supergraph_service(service) {
2
    let original = "alice and bob";
3
    let encoded = base64::encode(original);
4
    // encoded will be "YWxpY2UgYW5kIGJvYgo="
5
    try {
6
        let and_back = base64::decode(encoded);
7
        // and_back will be "alice and bob"
8
    }
9
    catch(err)
10
    {
11
        // log any errors
12
        log_error(`base64::decode error: ${err}`);
13
    }
14
}

ⓘ 注意

您不需要导入“base64”模块。它在router中已经导入。

不同的字母表

Base64支持多种字母表进行数据编码，具体取决于它所在环境中支持字符。路由器支持以下字母表：

STANDARD：定义在RFC 4648中的“base64”编码。这是未指定时的默认值。
STANDARD_NO_PAD：定义在RFC 4648中，没有了填充字符（=或==字符）。
URL_SAFE: 指的是在 RFC 4648 中定义的 "base64url" 编码
URL_SAFE_NO_PAD: 指的是在 RFC 4648 中定义的 "base64url" 编码，不含填充字符（= 或 == 字符在末尾）

要使用它们，我们可以在 encode 和 decode 方法中添加一个参数：

1
fn supergraph_service(service) {
2
    let original = "alice and bob";
3
    let encoded = base64::encode(original, base64::URL_SAFE);
4
    // encoded will be "YWxpY2UgYW5kIGJvYgo="
5
    try {
6
        let and_back = base64::decode(encoded, base64::URL_SAFE);
7
        // and_back will be "alice and bob"
8
    }
9
    catch(err)
10
    {
11
        // log any errors
12
        log_error(`base64::decode error: ${err}`);
13
    }
14
}

具有多个值的头部

处理单值头部的简单 get/set API 对于大多数用例来说已经足够了。如果您想对一个键设置多个值，则应提供值数组来自行设置。

如果您想获取头键的多个值，则必须使用 values() 函数，而不是索引访问器。如果您使用索引访问器，它将仅返回与键关联的第一个值（作为字符串）。

查看示例以了解其实际应用。

Unix时间戳

您的Rhai定制可以使用函数 unix_now() 以秒为单位从Unix纪元以来获取当前Unix时间戳。

1
fn supergraph_service(service) {
2
    let now = unix_now();
3
}

Unix时间戳（以毫秒为单位）

您的Rhai定制可以使用函数 unix_ms_now() 以毫秒为单位从Unix纪元以来获取当前Unix时间戳。

1
fn supergraph_service(service) {
2
    let now = unix_ms_now();
3
}

唯一标识符（UUID）

您的Rhai定制可以使用函数 uuid_v4() 获取UUIDv4 ID。

1
fn supergraph_service(service) {
2
    let id = uuid_v4();
3
}

环境变量

您的Rhai定制可以使用 env 模块访问环境变量。使用 env::get() 函数。

1
fn router_service(service) {
2
    try {
3
        print(`HOME: ${env::get("HOME")}`);
4
        print(`LANG: ${env::get("LANG")}`);
5
    } catch(err) {
6
        print(`exception: ${err}`);
7
    }
8
}

ⓘ 注意

您不需要导入 "env" 模块。它已包含在 router 中。
get()可能失败，因此在使用它时最好处理异常。

可用常量

router提供了对您的Rhai脚本大部分用于从上下文获取数据的常量。

1
Router.APOLLO_SDL // Context key to access the SDL
2
Router.APOLLO_START // Constant to calculate durations
3
Router.APOLLO_AUTHENTICATION_JWT_CLAIMS // Context key to access authentication jwt claims
4
Router.APOLLO_SUBSCRIPTION_WS_CUSTOM_CONNECTION_PARAMS // Context key to modify or access the custom connection params when using subscriptions in WebSocket to subgraphs (cf subscription docs)
5
Router.APOLLO_ENTITY_CACHE_KEY // Context key to access the entity cache key
6
Router.APOLLO_OPERATION_ID // Context key to get the value of apollo operation id (studio trace id) from the context

`Request` 接口

通过 map_request 注册的所有回调函数都会接收到一个 request 对象，该对象表示客户端发送的请求。此对象包含以下字段：

1
request.context
2
request.id
3
request.headers
4
request.method
5
request.body.query
6
request.body.operation_name
7
request.body.variables
8
request.body.extensions
9
request.uri.host
10
request.uri.path

ⓘ 注意

这些字段通常是可修改的，除了 method 外，该方法始终为只读。但是，当回调服务是 subgraph_service 时，唯一可修改的字段是 request.context.

仅针对 subgraph_service 回调， request 对象提供了 额外的 可修改的字段，用于与将发送给相应子图的请求进行交互：

1
request.subgraph.headers
2
request.subgraph.body.query
3
request.subgraph.body.operation_name
4
request.subgraph.body.variables
5
request.subgraph.body.extensions
6
request.subgraph.uri.host
7
request.subgraph.uri.path

`request.context`

上下文是一个通用的键/值存储，在整个客户端请求的生命周期中存在。您可以使用它来在请求的生命周期中共享信息。

键必须是字符串，但值可以是任何Rh daß 对象。

1
// You can interact with request.context as an indexed variable
2
request.context["contextual"] = 42; // Adds value 42 to the context with key "contextual"
3
print(`${request.context["contextual"]}`); // Writes 42 to the router log at info level
4
// Rhai also supports extended dot notation for indexed variables, so this is equivalent
5
request.context.contextual = 42;

`upsert()`

上下文提供了一个 upsert() 函数来解决在设置特定键的值时需要更新或插入的情况。

要使用 upsert()，您必须定义一个回调函数，该函数接收一个键的现有值（如果有的话）并将其修改，然后在返回最终要设置的值之前进行修改。

1
// Get a reference to a cache-key
2
let my_cache_key = response.headers["cache-key"];
3

4
// Define an upsert resolver callback
5
// The `current` parameter is the current value for the specified key.
6
// This particular callback checks whether `current` is an ObjectMap 
7
// (default is the unit value of ()). If not, assign an empty ObjectMap.
8
// Finally, update the stored ObjectMap with our subgraph name as key
9
// and the returned cache-key as a value.
10
let resolver = |current| {
11
  if current == () {
12
      // No map found. Create an empty object map
13
      current = #{};
14
  }
15
  // Update our object map with a key and value
16
  current[subgraph] = my_cache_key;
17
  return current;
18
};
19

20
// Upsert our context with our resolver
21
response.context.upsert("surrogate-cache-key", resolver);

`request.id`

此 ID 是一个字符串，在整个生命周期中唯一地标识请求/响应上下文。如果您有一个请求（或响应），您可以通过以下方式访问 ID。

1
print(`request id is: ${request.id}`);

`request.headers`

请求的标题可以作为可读/写的索引变量访问。键和值必须是有效的标题名称和值字符串。

1
// You can interact with request.headers as an indexed variable
2
request.headers["x-my-new-header"] = 42.to_string(); // Inserts a new header "x-my-new-header" with value "42"
3
print(`${request.headers["x-my-new-header"]}`); // Writes "42" into the router log at info level
4
// Rhai also supports extended dot notation for indexed variables, so this is equivalent
5
request.headers.x-my-new-header = 42.to_string();
6
// You can also set an header value from an array. Useful with the "set-cookie" header,
7
// Note: It's probably more useful to do this on response headers. Simply illustrating the syntax here.
8
request.headers["set-cookie"] = [
9
  "foo=bar; Domain=localhost; Path=/; Expires=Wed, 04 Jan 2023 17:25:27 GMT; HttpOnly; Secure; SameSite=None",
10
  "foo2=bar2; Domain=localhost; Path=/; Expires=Wed, 04 Jan 2023 17:25:27 GMT; HttpOnly; Secure; SameSite=None",
11
];
12
// You can also get multiple header values for a header using the values() fn
13
// Note: It's probably more useful to do this on response headers. Simply illustrating the syntax here.
14
print(`${request.headers.values("set-cookie")}`);

`request.method`

这是客户端请求的 HTTP 方法。

1
print(`${request.method}`); // Log the HTTP method

`request.body.query`

这是客户端提供的 GraphQL 操作字符串，用于执行。

要在查询规划发生之前修改此值，必须在 supergraph_service() 请求回调中进行。如果稍后修改它，将使用原始提供的 operation 字符串生成查询规划。

以下示例修改了传入的查询并将其转换为完全无效的游戏：

1
print(`${request.body.query}`); // Log the query string before modification
2
request.body.query="query invalid { _typnam }}"; // Update the query string (in this case to an invalid query)
3
print(`${request.body.query}`); // Log the query string after modification

`request.body.operation_name`

这是要执行的 GraphQL 操作的名称，如果请求中提供了名称。如果 request.body.query 包含多个操作定义，则此值必须存在。

以下是与operation_name交互的示例，请参见examples/op-name-to-header目录。

1
print(`${request.body.operation_name}`); // Log the operation_name before modification
2
request.body.operation_name +="-my-suffix"; // Append "-my-suffix" to the operation_name
3
print(`${request.body.operation_name}`); // Log the operation_name after modification

`request.body.variables`

这些是提供给操作的任何GraphQL变量的值。变量，它们以一个对象映射的形式暴露给Rhai。

1
print(`${request.body.variables}`); // Log all GraphQL variables

`request.body.extensions`

请求扩展可以读取或修改。它们以一个对象映射的形式暴露给Rhai。

1
print(`${request.body.extensions}`); // Log all extensions

`request.uri.host`

这是请求URI的主机组件，作为一个字符串。

修改客户端请求的此值没有任何效果，因为请求已经到达router。但是，在subgraph_service回调中修改request.subgraph.uri.host确实会修改router与相应subgraph通讯所使用的URI。

1
print(`${request.uri.host}`); // Log the request host

`request.uri.path`

这是请求URI的路径组件，作为一个字符串。

修改客户端请求的此值没有任何效果，因为请求已经到达router。但是，在subgraph_service回调中修改request.subgraph.uri.path确实会修改router与相应subgraph通讯所使用的URI。

1
print(`${request.uri.path}`); // log the request path
2
request.uri.path += "/added-context"; // Add an extra element to the query path

`request.subgraph.*`

仅在对subgraph_service中注册的map_request回调中，才可使用request.subgraph对象。该对象与request对象具有完全相同的fields，但这些fields适用于router将发送到相应subgraph的HTTP请求。

1
// You can interact with request.subgraph.headers as an indexed variable
2
request.subgraph.headers["x-my-new-header"] = 42.to_string(); // Inserts a new header "x-my-new-header" with value "42"
3
print(`${request.subgraph.headers["x-my-new-header"]}`); // Writes "42" into the router log at info level
4
// Rhai also supports extended dot notation for indexed variables, so this is equivalent
5
request.subgraph.headers.x-my-new-header = 42.to_string();

`Response`接口

通过map_response注册的所有回调函数都传入了表示HTTP响应的response对象。

在subgraph_service中，该对象表示相应subgraph发送给router的响应。
在其他所有服务中，此对象表示路由器将发送给请求客户端的响应。

响应对象包含以下字段：

1
response.context
2
response.id
3
response.status_code
4
response.headers
5
response.body.label
6
response.body.data
7
response.body.errors
8
response.body.extensions

上述所有字段都是可读写。

以下字段的行为与其请求对应字段相同：

上下文
id
头部
主体
主体扩展

在与响应上下文中的头部或状态码交互时请特别小心。对于router_service()、supergraph_service()和execution_service()，在延迟响应流中的第一个响应才存在头部和状态码。您可以通过使用is_primary()函数来处理这种情况，如果响应是第一个（或主要）响应，则它会返回true。如果您尝试访问非主要响应的头部或状态码，则将引发异常，这可以像处理任何其他Rhai异常一样处理，但不如使用is_primary()方法方便。

1
if response.is_primary() {
2
        print(`all response headers: ${response.headers}`);
3
    } else {
4
        print(`don't try to access headers`);
5
    }

其他字段如下所述。

`response.body.label`

响应可能包含一个标签，可以将其作为字符串读取/写入。

1
print(`${response.body.label}`); // logs the response label

`response.body.data`

响应可能包含数据（有些带有错误的响应不包含数据）。在操作数据（和错误）时请小心，以确保响应保持有效。data以对象映射的形式暴露给Rhai。

在examples/data-response-mutate目录中有一个与响应数据交互的完整示例。

1
print(`${response.body.data}`); // logs the response data

`response.body.errors`

响应可能包含错误。错误以Rhai中对象映射的数组形式表示。

每个错误必须包含至少以下内容：

消息（字符串）
位置（数组）

（位置可以是空数组。）

错误可选地还可以包含扩展，用作对象映射。

在examples/error-response-mutate目录中有一个与响应错误交互的完整示例。

1
// Create an error with our message
2
let error_to_add = #{
3
    message: "this is an added error",
4
    locations: [],
5
    // Extensions are optional, adding some arbitrary extensions to illustrate syntax
6
    extensions: #{
7
        field_1: "field 1",
8
        field_2: "field_2"
9
    }
10
};
11
// Add this error to any existing errors
12
response.body.errors += error_to_add;
13
print(`${response.body.errors}`); // logs the response errors

`response.status_code.to_string()`

将响应状态码转换为字符串。

1
if response.status_code.to_string() == "200" {
2
    print(`ok`);
3
}

如果要将响应状态码转换为数字，这也很有用

1
if parse_int(response.status_code.to_string()) == 200 {
2
    print(`ok`);
3
}

您也可以从整数创建自己的状态码

1
if response.status_code == status_code_from_int(200) {
2
    print(`ok`);
3
}

ⓘ 注意

`response.status_code` 对象仅对在 `router_service` 或 `subgraph_service` 中注册的 `map_response` 回调可用。

Rhai 脚本

外部协同处理

Rhai 脚本API参考

定制路由器API

入口钩子

记录

终止客户端请求

定时执行

访问SDL

访问TraceId

URL编码/解码字符串

JSON编码/解码字符串

Base64编码/解码字符串

不同的字母表

SHA256散列字符串

具有多个值的头部

Unix时间戳

Unix时间戳（以毫秒为单位）

唯一标识符（UUID）

环境变量

可用常量

`Request` 接口

`request.context`

`upsert()`

`request.id`

`request.headers`

`request.method`

`request.body.query`

`request.body.operation_name`

`request.body.variables`

`request.body.extensions`

`request.uri.host`

`request.uri.path`

`request.subgraph.*`

`Response`接口

`response.is_primary()`

`response.body.label`

`response.body.data`

`response.body.errors`

`response.status_code.to_string()`