@fanoutio/serve-grip

js-serve-grip (英语)

为 JavaScript 提供的 GRIP 库 express 财务报告和审定财务报表 hono 兼容的中间软件.

此库旨在协助创建后端服务器应用程序 使用 JavaScript 编写的 加纳。 。 。 . 该图书馆可通过以下框架使用:

• 快递
• 浩诺
• 下一个.js
• 连接
• 科亚 * 实验性支助

支持的GRIP服务器包括:

• 推动
• 快速闪出

作者:大武之子 库穆罗@ fastly.com康斯坦丁·博卡里乌斯 kon@ fanout.io (英语)

V3 新建

中断更改

• ServeGripBase 不再声明 monkeyPatchResMethodsForWebSocket 财务报告和审定财务报表 monkeyPatchResMethodsForGripInstruct 抽象的方法。 相反, 结尾处 run 方法,该 onAfterSetup() 方法被称为.

增强

• 现在添加支持 浩诺 框架.

使用量

导言

加纳 是允许网络服务使用 代理实时将行为推向代理组件,使用HTTP和头.

@fanoutio/serve-grip 是一个服务器中间软件,它与 Express 和 何诺. 它会:

• 提供一个简单而直截了当的方法来配置这些框架与您的 GRIP 代理
• 描述 Grip-Sig 在任何检测是否通过 Grip 代理请求中的页眉
• 为您的路由处理器提供处理此类请求的工具,例如:
  • 访问当前请求是代理还是签名的信息
  • 您可以调用的方法向 GRIP 代理发布任何指令
• 提供进入 Publisher 对象,允许您的应用程序通过 gRIP出版社.

此外, serve-grip 也处理 WebSocket- Over- HTTP 处理 这样 由 GRIP 代理管理的 WebSocket 连接可由您的路由处理器控制 .

安装

安装库.

npm install @fanoutio/serve-grip

在快件/ 连接中安装

导入 ServeGrip 课程从 @fanoutio/serve-grip/node 将中间的软件立即释放 那先装好 你的路线.

示例

import express from 'express';
import { ServeGrip } from '@fanoutio/serve-grip/node';

const app = express();

const serveGripMiddleware = new ServeGrip(/* config */);
app.use(serveGripMiddleware); 

app.use('/path', (res, req) => {

    if (req.grip.isProxied) {
        const gripInstruct = res.grip.startInstruct();
        gripInstruct.addChannel('test');
        gripInstruct.setHoldStream();
        res.end('[stream open]\n');
    }

});

app.listen(3000);

在Hono安装

[注] 强烈建议使用 类型脚本 和浩诺合作的时候.

导入 serveGrip 函数从 @fanoutio/serve-grip/hono 将中间的软件立即释放 那先装好 你的路线.

指定配置对象 serveGrip 可以在召回中完成。 这对这样的环境很有用 用于快速计算,其中在请求处理前可能无法进行配置.

此外,导入 Env 键入并当即时使用 Hono类型 检查 c.var.grip 上下文变量.

示例

import { serve } from '@hono/node-server';
import { Hono } from 'hono';
import { serveGrip, type Env } from '@fanoutio/serve-grip/hono';

const app = new Hono<Env>();

const serveGripMiddleware = serveGrip(() => /* config */);
app.use(serveGripMiddleware);

app.use( '/path', async (c) => {

    if (c.var.grip.isProxied) {
        const gripInstruct = c.var.grip.startInstruct();
        gripInstruct.addChannel(CHANNEL_NAME);
        gripInstruct.setHoldStream();
        return c.text('[stream open]\n');
    }

});

serve({ fetch: app.fetch, port: 3000 }, (addr) => {
    console.log(`Example app listening on port ${addr.port}!`)
});

[注] 以上的例子为Hono在Node.js上运行. 何诺可以使用 其他服务器平台也是如此。 关于修改应用程序使之适应 其他平台,见 浩诺的向导。 。 。 .

在后端应用程序运行时使用此库的实例 在“快速计算”上,检查以下示例应用程序:

• hono-compute-http (韩语)
• 胡诺计算

在Koa安装(实验)

导入 ServeGrip 课程从 @fanoutio/serve-grip/node 并立即进行。 Koa 中间软件可用 作为 .koa 对象上的属性。 在你的路线前安装它.

示例

import Koa from 'koa';
import Router from '@koa/router';
import { ServeGrip } from '@fanoutio/serve-grip/node';

const app = new Koa();

const serveGripMiddleware = new ServeGrip(/* config */);
app.use(serveGripMiddleware.koa);

const router = new Router();

router.use( '/path', ctx => {

    if (ctx.req.grip.isProxied) {
        const gripInstruct = res.grip.startInstruct();
        gripInstruct.addChannel('test');
        gripInstruct.setHoldStream();
        ctx.body = '[stream open]\n';
    }

});

app.use(router.routes())
    .use(router.allowedMethods());

app.listen(3000);

在下一个.js安装

您可以使用此库将 GRIP 功能添加到您的 Next.js API 路由。 。 。 .

导入 ServeGrip 课程从 @fanoutio/serve-grip/node 将中间的软件立即放入 您的处理器在应用程序逻辑之前, 通过调用 async 函数 serveGripMiddleware.run()。 。 。 .

示例 /lib/grip.js数字 :

import { ServeGrip } from '@fanoutio/serve-grip/node';
export const serveGripMiddleware = new ServeGrip(/* config */);

/pages/api/path.js数字 :

import { serveGripMiddleware } from '/lib/grip';

export default async(req, res) => {
    // Run the middleware
    if (!(await serveGripMiddleware.run(req, res))) {
        // If serveGripMiddleware.run() has returned false, it means the middleware has already
        // sent and ended the response, usually due to an error.  
        return;
    }

    if (req.grip.isProxied) {
        const gripInstruct = res.grip.startInstruct();
        gripInstruct.addChannel('test');
        gripInstruct.setHoldStream();
        res.end('[stream open]\n');
    }

}

[注] 在 Next.js 中,您必须特别从每个应用的 API 路由中调用中间软件 . 这是因为在 Next.js 中,您的 API 路由通常会在无服务器的平台上运行, 对象 每次请求后都会被回收。 建议您构建一个单通实例 在共享位置的中间软件,并从您的 API 路由中引用 .

配置

@fanoutio/serve-grip/node 导出一个命名的类构造器 ServeGrip此构造器需要 用于配置实例的配置对象, 如要使用的 GRIP 代理 用于发布或收到的请求是否需要GRIP代理.

以下是GRIP代理作为实例时的配置实例: 在本地主机上驱动运行 :

import { ServeGrip } from '@fanoutio/serve-grip/node';
const serveGripMiddleware = new ServeGrip({
    grip: {
        control_uri: 'https://localhost:5561/',   // Control URI for Pushpin publisher
        control_iss: '<issuer>',                  // (opt.) iss needed for publishing, if required by Pushpin
        key: '<publish-key>',                     // (opt.) key needed for publishing, if required by Pushpin
    },
    isGripProxyRequired: true,
});

以下为GRIP代理快速Fanout时的配置示例:

import { ServeGrip } from '@fanoutio/serve-grip/node';
const serveGripMiddleware = new ServeGrip({
    grip: {
        control_uri: 'https://api.fastly.com/service/<service-id>/',   // Control URI
        key: '<fastly-api-token>',             // Authorization key for publishing (Fastly API Token)
        verify_iss: 'fastly:<service-id>',     // Fastly issuer used for validating Grip-Sig
        verify_key: '<verify-key>',            // Fastly public key used for validating Grip-Sig
    },
    isGripProxyRequired: true,
});

配置通常使用 GRIP_URL (如有需要, GRIP_VERIFY_KEY),允许使用简单的字符串进行配置。 这允许从环境变量进行配置:

GRIP_URL="https://api.fastly.com/service/<service-id>/?verify-iss=fastly:<service-id>&key=<fastly-api-token>"
GRIP_VERIFY_KEY="base64:LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZrd0V3WUhLb1pJemowQ0FRWUlLb1pJemowREFRY0RRZ0FFQ0tvNUExZWJ5RmNubVZWOFNFNU9uKzhHODFKeQpCalN2Y3J4NFZMZXRXQ2p1REFtcHBUbzN4TS96ejc2M0NPVENnSGZwLzZsUGRDeVlqanFjK0dNN3N3PT0KLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0t"

import { ServeGrip } from '@fanoutio/serve-grip/node';

const serveGripMiddleware = new ServeGrip({
    grip: process.env.GRIP_URL,
    gripVerifyKey: process.env.GRIP_VERIFY_KEY,
    isGripProxyRequired: true,
});

[注] 当和浩诺一起使用时, @fanoutio/serve-grip/hono 导出一个名为函数的函数 serveGrip 而不是一个建筑师. 此函数将对象与参数相同 ServeGrip 或承诺 解决此对象。 也可以使用回调来称呼它,以返回这样的对象或承诺. 这对快速计算等环境有用, 运行时配置可能要到 请求处理.

示例

import { serveGrip } from '@fanoutio/serve-grip/hono';

const serveGripMiddleware = serveGrip(async () => {
    const gripUrl = await loadGripUrl();
    return {
        grip: gripUrl,
    };
});

可用的选项 :

在多数情况下,您的应用程序会构造此类的单通实例并用作 中间的软件.

这个 grip 参数可以是下列任何一种:

1. 以下字段为对象:

   外地	说明
   control_uri	GRIP客户端的控制URI.
   control_iss	(可选)控制国际空间站,如果GRIP客户要求.
   key	(可选)字符串或 Uint8Array 。 如果GRIP客户端需要,用于控制国际空间站的密钥.
   verify_iss	(可选) 用于验证GRIP签名的空间站.
   verify_key	(可选)字符串或 Uint8Array 。 用于验证 GRIP 签名的密钥 .

2. 此类对象的阵列 .

3. A GRIP URI,是将上方编码为单字符串的字符串.

4. (高级)A Publisher 对象,从 @fanoutio/grip。 。 。 .

处理路径

在中间软件运行后, 您的处理器将接收 Grip 上下文 grip 联 合 国 req 财务报告和审定财务报表 res 对象或在Hono上 上下文 c) (中文(简体) ). 这些设施提供下列服务:

要发布信件,请获取 Publisher。使用它发布消息,使用中间软件初始化时指定的端点和前缀.

实例

该寄存器包含一些实例,以说明使用 serve-grip 在连接/快递中 和下一个.js,可在 examples 目录。 欲了解每个例子的详细情况,请 读取 README.md 在相应的目录中的文件.

高级

快速计算

快速计算 是高级 运行代码的边缘计算平台(被编译为WebAssembly)在快取的全球边缘网络上.

当使用快速计算时,单个应用程序可以同时使用 启动 GRIP 移交 财务报告和审定财务报表 进程代理GRIP 请求 将应用程序本身配置为后端。 在这个设定中,应用程序运行 两次 按请求:

• 一次作为 外部计算应用程序,激活 GRIP 代理服务器
• 再次作为 内部代理应用程序,通过GRIP代理引用.

为了支持这种模式, @fanoutio/serve-grip/hono 提供了额外的Hono中间软件, fanoutSelfHandoffMiddleware,它会在快速计算 JavaScript 下运行时自动包含 SDK(通过 fastly 有条件的运行时间密钥) (中文(简体) ).

import { fanoutSelfHandoffMiddleware } from '@fanoutio/serve-grip/hono';

app.get('/api/*', fanoutSelfHandoffMiddleware('self'));

此中间软件检查应用程序是否在外部计算上下文中运行, 或是内在的代理上下文 :

• 在那个 外部 上下文,它执行 Fanout 交接回 'self',必须定义为您的后端 快速服务 指向自己.
• 在那个 内 上下文中,它允许继续请求.

[注] 此寄存器中的例子以 快速 Fanout 本地测试数字 :

• hono-compute-http (韩语)
• 胡诺计算

在向您的快速账户部署时,确保:

1. Fanout 已启用 为你服务,和
2. A 类 指向自己的后端 已配置.

详情见 部署到快递处 在快速文档中.

许可证

(C)2015,2020 Fanout, Inc.
(C)2025快通股份有限公司. 根据麻省理工学院的许可,详情见文件LICENSE.md.