elysia-protobuf

Easy support protobuf integration for Elysia, powered by @bufbuild/protobuf and schemas generated by ts-proto

Install

bun install elysia-protobuf

Before Starting

One small setup detail: register protobuf() directly on the root new Elysia() instance

Registering it only inside a group doesn't make the protobuf parser available to that group's routes

Usage

Use TProtobuf() in Elysia's standard body and response route schemas

Give it a schema generated by ts-proto, not a TypeBox schema

import Elysia from "elysia";
import { protobuf, TProtobuf } from "elysia-protobuf";
import {
  RequestMessage,
  ResponseMessage,
  ResponseStatus,
} from "./proto/message";

const app = new Elysia()
  .use(
    protobuf({
      // Optional request signature verification
      signature: {
        enabled: true,
        secret: "test123",
        headerName: "x-signature",
      },
    }),
  )
  .post(
    "/post",
    ({ body }) => {
      return {
        status: ResponseStatus.SOME,
        inlineTags: body.tags.join(", "),
      };
    },
    {
      parse: "protobuf",
      body: TProtobuf(RequestMessage),
      response: TProtobuf(ResponseMessage),
    },
  )
  .listen(3000);

When using response: TProtobuf(...), return a plain object because a directly returned Response bypasses protobuf response encoding

Error Handling

Signature failures are parser errors, so import error classes from elysia-protobuf/error and check the error cause in an onError hook

import { ProtoRequestError } from "elysia-protobuf/error";

const app = new Elysia().use(protobuf()).onError(({ code, error }) => {
  if (code === "PARSE" && error.cause instanceof ProtoRequestError) {
    return {
      message: error.cause.message,
    };
  }
});

Set signature.showParseErrors to false to use Elysia's default parser-error response

It defaults to true

Create a Protobuf Schema

1. Install protoc
2. Install ts-proto package
3. Convert .proto to .ts with ts-proto (see example for details):

protoc --plugin=.\\node_modules\\.bin\\protoc-gen-ts_proto --ts_proto_opt=esModuleInterop=true --ts_proto_opt=importSuffix=.js --ts_proto_out=./src ./proto/*.proto

4. Import schemas from ./src/proto/YOUR_FILE.ts

Options

| Key | Type | Default | Description | | --------------------------- | --------- | --------------- | ------------------------------------------------- | | signature.enabled | boolean | false | Enables request signature verification | | signature.secret | string | "replaceme" | HMAC secret | | signature.headerName | string | "x-signature" | Header containing the hexadecimal signature | | signature.showParseErrors | boolean | true | Returns signature parser-error messages to client |

new Elysia().use(
  protobuf({
    signature: {
      enabled: true,
      secret: "changeme",
      headerName: "x-signature",
      showParseErrors: true,
    },
  }),
);