@ autonomys/ rpc

本套件旨在通过下列功能来方便自定义的RPC协议的执行:

• 强大的连接控制器(如重联手柄).
• 内建RPC协议.
• 创建类型安全的 api 定义 .

类型安全 RPC API

此软件包的目标之一是在实施RPC服务器时实现类型安全,并方便RPC客户端的创建.

为了解决这个问题,我们应该建立一个 ApiDefinition 基本上包括RPC方法的定义及其投入或输出.

示例

const apiDefinition = createApiDefinition({
  test: {
    params: z.object({ name: z.string() }),
    returns: z.object({ name: z.string() }),
  },
})

上面的对象定义了带有单个的 RPC 服务器 test 作为参数接收的方法 { name: string } 并返回同样的.

通常,我们想要验证 输入和输出 正在正确构建 尊重定义的类型。 因此,类型定义接受任何 标准Schema (如zod, Valibot 或 ArkType). 与zod的验证需要zod QQ 3.24:更古老的版本不执行标准Schema,因此他们的计数计划无法进行打字检查. 但是,如果出于某种原因,你不想执行验证器,你可以使用这种方法 defineUnvalidatedType<T>()数字 :

type TypeWithNoValidation = string // Any type could be used here

const apiDefinition = createApiDefinition({
  test: {
    params: z.object({ name: z.string() }),
    returns: defineUnvalidatedType<TypeWithNoValidation>(),
  },
})

参数和结果作为JSON发送并解析到另一边,所以一个有变换或默认的图案有两种. 客户端发送图解输入 params 和处理器获得解析输出,而处理器返回 returns 和客户端获得解析输出。 例如,与 returns: z.string().transform((s) => new Date(s)) 处理器返回字符串,客户端得到一个 Date一些计划 unknown 作为输入,例如 z.coerce.number() 在 zod 4 中,或 z.preprocess(...),所以客户端接受那里的任何值,只有服务器拒绝. 在Zod 4 中,我们没有在Zod 4中, z.coerce.number<number>() 再次设置输入类型.

定义服务器 RPC 处理器

一旦我们的API接口被定义,服务器RPC处理器应该被定义:

const apiDefinition = createApiDefinition({
  test: {
    params: z.object({ name: z.string() }),
    returns: defineUnvalidatedType<TypeWithNoValidation>(),
  },
})

const server = apiDefinition.createServer({
  test: (params) => {
    return {
      name: params.name,
    }
  },
})

server.listen(8080)

您也可以通过 HTTP 服务器、 Express 应用程序或端口 :

const server = apiDefinition.createServer(
  {
    test: (params) => ({ name: params.name }),
  },
  {
    httpServer: app, // Express app or http.Server instance
    port: 8080,
  },
)

使用类型安全 RPC 客户端

一旦服务器运行,使用相同的API定义,客户端可以简单地通过:

const apiDefinition = createApiDefinition({
  test: {
    params: z.object({ name: z.string() }),
    returns: defineUnvalidatedType<TypeWithNoValidation>(),
  },
})

const client = apiDefinition.createClient({
  endpoint: `<ws-server-endpoint>`,
  callbacks: {},
})

client
  .test({
    name: 'log',
  })
  .then((e) => console.log(e)) /// { name: "xyz" }

设置 RPC 服务器 (w/o 类型安全)

您可以使用 createRpcServer 函数带有初始处理器的可选列表。 您可以直接在端口上收听或附着到已有的 HTTP 服务器/ Express app:

import { createRpcServer } from '@autonomys/rpc'

const rpcServer = createRpcServer({
  initialHandlers: [
    {
      method: 'test',
      handler: () => ({
        jsonrpc: '2.0',
        result: 'success',
        id: 1,
      }),
    },
  ],
})

rpcServer.listen(8080)

或者通过 port 或快递 app 直接 :

const rpcServer = createRpcServer({
  httpServer: app, // optional: Express application or http.Server
  port: 8080,      // optional: auto-starts listening on port
  initialHandlers: [...],
})

设置 RPC 客户端( w/o 类型安全)

您可以通过使用 createRpcClient 函数。 此函数需要一个 WS( S) 端点, 并为某些事件设置回调 。 以下是如何设置的例子:

import { createRpcClient } from '../../src'

const setupRpcClient = async () => {
  const rpcClient = createRpcClient({
    endpoint: `ws://localhost:8080`,
    callbacks: {},
  })

  return rpcClient
}

// Example usage
const rpcClient = await setupRpcClient()

const response = await rpcClient.send({
  jsonrpc: '2.0',
  method: 'test',
  id: 1,
  params: {},
})

console.log(response)