Migrate the generated TypeScript bindings from ts-proto to protobuf-es v2

Abierto
  • ¿Algo no está bien?
#3,632 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
30/100
Tipo de issue
Refactorización
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
grpc, typescript
Área
api, frontend

Línea de trabajo

Start in app/controlplane/api/buf.gen.yaml, which holds the ts-proto plugin entry, and then run make api to see the current output in gen/frontend. The work is to swap the generator to buf.build/bufbuild/es with target=ts and include_imports: true, remove the old ts-proto files, and regenerate. Done means the acceptance criteria hold: no @improbable-eng/grpc-web, browser-headers or protobufjs imports, and no diff from make api in CI. The consumer migration and breaking-change plan still need a maintainer decision.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

component/frontend dependencies

Summary

Migrate the generated TypeScript bindings of the control plane API from ts-proto to protobuf-es v2 (@bufbuild/protobuf v2). Use Connect-ES v2 (@connectrpc/connect v2) for the clients.

Current state

app/controlplane/api/buf.gen.yaml generates the TypeScript bindings with ts-proto:

- remote: buf.build/community/stephenh-ts-proto:v1.151.1
  out: ./gen/frontend
  opt:
    - outputClientImpl=grpc-web
    - esModuleInterop=true
    - useOptionals=messages
  • The output goes to app/controlplane/api/gen/frontend.
  • The output contains the control plane, attestation, workflow contract, errors and jsonfilter protos.
  • The output also contains third-party imported protos. Examples: protoc-gen-openapiv2/options/annotations.ts, protoc-gen-openapiv2/options/openapiv2.ts, buf/validate/... and google/api/....
  • The generated code depends on @improbable-eng/grpc-web, browser-headers and protobufjs/minimal.

This is the only buf.gen.yaml in the repository that emits TypeScript. The other files (app/artifact-cas/api, pkg/attestation/crafter/api, pkg/credentials/api, the plugin SDK and the conf packages) emit Go only. So the scope is this one file and its output folder.

Motivation

  • ts-proto with the improbable-eng grpc-web transport is in maintenance mode.
  • protobuf-es v2 and Connect-ES v2 are the stack that Buf maintains. They have a smaller runtime, first-class ESM and TypeScript support, and they pass the Protobuf conformance tests.
  • Some downstream consumers already generate their own protos with protobuf-es v2 into the same source tree. Today they get two different generated files for the same imported proto. For example, protoc-gen-openapiv2/options/annotations.ts from ts-proto sits next to annotations_pb.ts from protobuf-es. The consumers must filter files out when they sync the bindings. One generator for all bindings removes this problem.

Proposed implementation

1. Replace the generator plugin

protobuf-es v2 also generates the service descriptors. A separate connect-es plugin is not necessary.

- remote: buf.build/bufbuild/es:v2.16.0
  out: ./gen/frontend
  opt: target=ts
  include_imports: true

include_imports: true generates the imported dependencies (openapiv2 options, buf/validate, google/api) as *_pb.ts files. Consumers then get a self-contained set of files.

2. Changes in the generated code
  • File names change to <name>_pb.ts.
  • Messages are plain types. Create them with create(FooSchema, {...}).
  • Serialize with toBinary, fromBinary, toJson and fromJson from @bufbuild/protobuf.
  • Enums are TypeScript enums.
  • Oneofs use the { case, value } form.
  • Use @bufbuild/protobuf/wkt for Timestamp (timestampDate, timestampFromDate).
3. Clients
  • Create clients with createClient(Service, transport) from @connectrpc/connect v2.
  • Use createGrpcWebTransport from @connectrpc/connect-web v2. The transport stays gRPC-web, so the server needs no change.
  • Remove the @improbable-eng/grpc-web, browser-headers and protobufjs dependencies.
import { createClient } from "@connectrpc/connect";
import { createGrpcWebTransport } from "@connectrpc/connect-web";
import { WorkflowService } from "./controlplane/v1/workflow_pb";

const transport = createGrpcWebTransport({ baseUrl: "https://cp.example.com" });
const client = createClient(WorkflowService, transport);
4. Transition
  • This is a breaking change for every consumer of gen/frontend.
  • If a transition period is necessary, emit the protobuf-es output to a new folder first (for example gen/frontend-es). Keep the ts-proto output in gen/frontend until the consumers migrate. Then remove the ts-proto plugin.
5. Regeneration and CI
  • Run make api from the repository root (it runs buf generate in app/controlplane/api) and commit the new output.
  • Remove the old ts-proto files from the output folder. buf generate does not delete stale files.
  • The test.yml workflow runs make api and fails if the tree is dirty. The regenerated files must be in the same pull request.

Acceptance criteria

  • app/controlplane/api/buf.gen.yaml uses buf.build/bufbuild/es v2 with target=ts and include_imports: true.
  • The generated output has no imports of @improbable-eng/grpc-web, browser-headers or protobufjs.
  • The generated output contains the imported third-party protos as *_pb.ts files.
  • make api produces no diff in CI.
  • The release notes state the breaking change for consumers of gen/frontend.

🤖 Posted by Maximus bot (Claude Code) on behalf of @migmartri

Lenguaje dominante
Go
Estrellas
582
Forks
61
Merge medio
12 h 47 min
PR fusionados (30 d)
137

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de chainloop-dev/chainloop

Todos los issues de chainloop-dev/chainloop

Issues similares

Más issues de Go

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.