feat(08): add TypeScript server generator (#121)

* feat(08): add TypeScript server generator (protoc-gen-ts-server)

Extract shared TS type mapping into internal/tscommon/ and add a new
framework-agnostic TypeScript HTTP server generator that uses the Web
Fetch API (Request → Promise<Response>).

- Extract tscommon from tsclientgen (types.go, helpers.go) — zero behavior change
- Add tsservergen with handler interfaces, route descriptors, header validation
- Add 13 golden tests + cross-generator consistency tests vs ts-client
- Update CLAUDE.md with ts-server documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(08): add path param merge, generation-time validation, and fullstack demo

Path params are now merged into the request body after parsing
(body.id = pathParams["id"]) so handlers receive complete request
objects. Generation fails fast for invalid protos: unmatched path
params and unreachable fields on GET/DELETE methods.

Adds examples/ts-fullstack-demo/ showing TS client + TS server
generated from the same proto, with CRUD, query params, unwrap,
header validation, and custom error handling.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: add protoc-gen-ts-server to all project documentation

Update README, architecture, getting-started, client-generation,
examples index, and contributing docs to reflect the new TypeScript
HTTP server generator and the ts-fullstack-demo example.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(08): add interactive browser UI with live server log streaming

Serves an HTML dashboard at / with clickable buttons for all CRUD
operations, query params, unwrap, and error handling scenarios.
Server logs stream to the browser in real-time via SSE so you can
see handler activity as you click.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(08): add proto-defined custom errors and comprehensive request/response logging

Generator: CollectServiceMessages now includes proto messages ending with
"Error", mirroring Go's convention where error messages auto-implement the
error interface. Both ts-server and ts-client generators emit interfaces
for NotFoundError, LoginError, etc.

Demo: proto-defined NotFoundError and LoginError with full round-trip —
server implements generated interfaces, client parses ApiError.body using
generated types. Added Login Error (401) scenario to browser UI.

Server and client now log full request/response details (method, path,
headers, body, status, duration) with colored terminal output.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: add TypeScript proto-defined custom error documentation

Update all project docs to cover the new feature where both TS generators
(ts-client, ts-server) emit TypeScript interfaces for proto messages
ending with "Error". Documents the full pattern: proto definition →
generated interfaces → server implements + client parses for type-safe
error handling across the wire.

Updated: CLAUDE.md, architecture.md, client-generation.md, examples
README, http-generation.md, validation.md.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: SebastienMelki

CLAUDE.md

@@ -4,11 +4,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-This is `sebuf`, a specialized Go protobuf toolkit for building HTTP APIs. It consists of four complementary protoc plugins that together enable modern, type-safe API development:
+This is `sebuf`, a specialized Go protobuf toolkit for building HTTP APIs. It consists of five complementary protoc plugins that together enable modern, type-safe API development:
 
 - **`protoc-gen-go-http`**: Generates HTTP handlers, routing, request/response binding, and automatic validation
 - **`protoc-gen-go-client`**: Generates type-safe Go HTTP clients with functional options pattern
 - **`protoc-gen-ts-client`**: Generates TypeScript HTTP clients with full type safety, header helpers, and error handling
+- **`protoc-gen-ts-server`**: Generates TypeScript HTTP server handlers using the Web Fetch API (Request/Response), framework-agnostic
 - **`protoc-gen-openapiv3`**: Creates comprehensive OpenAPI v3.1 specifications
 
 The toolkit enables developers to build HTTP APIs directly from protobuf definitions without gRPC dependencies, targeting web and mobile API development with built-in request validation.
@@ -21,10 +22,13 @@ The project follows a clean Go protoc plugin architecture with separated concern
 - **cmd/protoc-gen-go-http/**: HTTP handler generator entry point
 - **cmd/protoc-gen-go-client/**: Go HTTP client generator entry point
 - **cmd/protoc-gen-ts-client/**: TypeScript HTTP client generator entry point
+- **cmd/protoc-gen-ts-server/**: TypeScript HTTP server generator entry point
 - **cmd/protoc-gen-openapiv3/**: OpenAPI specification generator entry point
 - **internal/httpgen/**: HTTP handler generation logic, annotations, and header validation middleware
 - **internal/clientgen/**: Go HTTP client generation logic and annotations
-- **internal/tsclientgen/**: TypeScript HTTP client generation logic, type mapping, and annotations
+- **internal/tscommon/**: Shared TypeScript type mapping and generation (used by ts-client and ts-server)
+- **internal/tsclientgen/**: TypeScript HTTP client generation logic
+- **internal/tsservergen/**: TypeScript HTTP server generation logic, header validation, route creation
 - **internal/openapiv3/**: OpenAPI generation logic, type mapping, and header parameter generation
 - **proto/sebuf/http/**: HTTP annotation definitions including headers.proto for header validation
 - **scripts/**: Test automation and build scripts
@@ -34,8 +38,10 @@ The project follows a clean Go protoc plugin architecture with separated concern
 1. **HTTP Handler Generator** (`internal/httpgen/generator.go:22`): Generates HTTP handlers, request binding, routing configuration, automatic body validation, and header validation middleware
 2. **Go HTTP Client Generator** (`internal/clientgen/generator.go:13`): Generates type-safe Go HTTP clients with functional options pattern, automatic request/response marshaling, and error handling
 3. **TypeScript HTTP Client Generator** (`internal/tsclientgen/generator.go`): Generates TypeScript HTTP clients with typed interfaces, service/method header helpers, query parameter encoding, path parameter substitution, and structured error handling (ValidationError/ApiError)
-4. **OpenAPI Generator** (`internal/openapiv3/generator.go:53`): Creates comprehensive OpenAPI v3.1 specifications from protobuf definitions with full header parameter support, generating one file per service for better organization
-4. **HTTP Annotations** (`proto/sebuf/http/annotations.proto`): Custom protobuf extensions for HTTP configuration
+4. **TypeScript HTTP Server Generator** (`internal/tsservergen/generator.go`): Generates framework-agnostic TypeScript HTTP server handlers using the Web Fetch API (`Request` → `Promise<Response>`), with route descriptors, header validation, query/body parsing, and error handling
+5. **OpenAPI Generator** (`internal/openapiv3/generator.go:53`): Creates comprehensive OpenAPI v3.1 specifications from protobuf definitions with full header parameter support, generating one file per service for better organization
+6. **Shared TypeScript Types** (`internal/tscommon/`): Shared TypeScript type mapping, interface generation, error types, and proto-defined error message collection (messages ending with "Error") used by both ts-client and ts-server generators
+7. **HTTP Annotations** (`proto/sebuf/http/annotations.proto`): Custom protobuf extensions for HTTP configuration
 5. **Header Validation** (`proto/sebuf/http/headers.proto`): Protobuf definitions for service and method-level header validation
 6. **Validation System**: Automatic request body validation via buf.validate/protovalidate and header validation middleware
 
@@ -93,11 +99,45 @@ try {
   if (e instanceof ValidationError) {
     console.log(e.violations);  // Field-level validation errors
   } else if (e instanceof ApiError) {
-    console.log(e.statusCode, e.message);
+    // Parse proto-defined custom errors using generated interfaces
+    const body = JSON.parse(e.body) as NotFoundError;
+    console.log(body.resourceType, body.resourceId);
   }
 }
 ```
 
+**TypeScript HTTP Servers** - Framework-agnostic server with Web Fetch API:
+```typescript
+// Generated handler interface (like Go's XxxServer)
+export interface UserServiceHandler {
+  createUser(ctx: ServerContext, req: CreateUserRequest): Promise<User>;
+  getUser(ctx: ServerContext, req: GetUserRequest): Promise<User>;
+}
+
+// Route creation — wire into any framework (Express, Hono, Bun, etc.)
+const routes: RouteDescriptor[] = createUserServiceRoutes(handler, {
+  onError: (err, req) => new Response("Internal error", { status: 500 }),
+  validateRequest: (method, body) => myValidator(method, body),
+});
+
+// Each route: { method: "POST", path: "/api/v1/users", handler: (req) => Response }
+// Handlers do: validate headers → parse body/query → optional validation → call handler → JSON response
+
+// Works natively in Node 18+, Deno, Bun, Cloudflare Workers
+// Example with Bun:
+Bun.serve({
+  fetch(req) {
+    const url = new URL(req.url);
+    for (const route of routes) {
+      if (req.method === route.method && matchPath(url.pathname, route.path)) {
+        return route.handler(req);
+      }
+    }
+    return new Response("Not Found", { status: 404 });
+  },
+});
+```
+
 **OpenAPI Specifications** - Comprehensive API documentation (one file per service):
 ```yaml
 # UserService.openapi.yaml
@@ -479,6 +519,7 @@ service UserService {
 ### Error Handling
 - **Structured Error Responses**: All errors use protobuf messages for consistent API responses
 - **Automatic Go Error Interface**: Any protobuf message ending with "Error" automatically implements Go's error interface for `errors.As()` and `errors.Is()` support
+- **Automatic TypeScript Error Interfaces**: Both TS generators (`protoc-gen-ts-client`, `protoc-gen-ts-server`) generate TypeScript interfaces for proto messages ending with "Error", enabling type-safe custom error handling across server and client
 - **Proto Message Error Preservation**: Custom proto error messages returned from handlers are serialized directly, preserving their structure (not wrapped in a generic Error message)
 - **Validation Errors (HTTP 400)**: ValidationError with field-level violations for body and header validation failures
 - **Handler Errors (HTTP 500)**: Error messages for service implementation failures with custom messages
@@ -490,15 +531,21 @@ service UserService {
 
 **Custom Proto Error Example:**
 ```protobuf
-// Define a custom error message
+// Define custom error messages — works across Go, TS server, and TS client
 message NotFoundError {
   string resource_type = 1;
   string resource_id = 2;
 }
+
+message LoginError {
+  string reason = 1;
+  string email = 2;
+  int32 retry_after_seconds = 3;
+}
 ```
 
 ```go
-// Return it from your handler - it will be serialized directly
+// Go: Return it from your handler - it will be serialized directly
 func (s *Server) GetUser(ctx context.Context, req *GetUserRequest) (*User, error) {
     user, err := s.db.FindUser(req.Id)
     if err != nil {
@@ -513,6 +560,19 @@ func (s *Server) GetUser(ctx context.Context, req *GetUserRequest) (*User, error
 // NOT: {"message":"{\"resourceType\":\"user\",\"resourceId\":\"123\"}"}
 ```
 
+```typescript
+// TS Server: implement generated interface, serialize in onError hook
+class NotFoundError extends Error implements NotFoundErrorType {
+  resourceType: string;
+  resourceId: string;
+  // ... constructor
+}
+
+// TS Client: parse ApiError.body using generated interface
+const body = JSON.parse(e.body) as NotFoundError;
+console.log(body.resourceType, body.resourceId);
+```
+
 ## Type System
 
 The plugin handles comprehensive protobuf-to-Go type mapping in `getFieldType()` (generator.go:118):
@@ -544,11 +604,14 @@ The repository contains:
 - **cmd/protoc-gen-go-http/**: HTTP handler plugin entry point
 - **cmd/protoc-gen-go-client/**: Go HTTP client plugin entry point
 - **cmd/protoc-gen-ts-client/**: TypeScript HTTP client plugin entry point
+- **cmd/protoc-gen-ts-server/**: TypeScript HTTP server plugin entry point
 - **cmd/protoc-gen-openapiv3/**: OpenAPI generation plugin entry point
-- **internal/annotations/**: Shared annotation parsing used by all 4 generators (unwrap, query params, headers, JSON mapping)
+- **internal/annotations/**: Shared annotation parsing used by all 5 generators (unwrap, query params, headers, JSON mapping)
 - **internal/httpgen/**: HTTP handler generation logic and tests
 - **internal/clientgen/**: Go HTTP client generation logic and tests
+- **internal/tscommon/**: Shared TypeScript type mapping and generation (interfaces, enums, error types)
 - **internal/tsclientgen/**: TypeScript HTTP client generation logic and tests
+- **internal/tsservergen/**: TypeScript HTTP server generation logic and tests
 - **internal/openapiv3/**: OpenAPI generation logic and comprehensive test suite
 - **examples/ts-client-demo/**: End-to-end TypeScript client example with NoteService CRUD API
 - **scripts/run_tests.sh**: Advanced test runner with coverage analysis and reporting

CONTRIBUTING.md

@@ -179,11 +179,14 @@ sebuf/
 │   ├── protoc-gen-go-http/           # HTTP handler generator
 │   ├── protoc-gen-go-client/         # Go HTTP client generator
 │   ├── protoc-gen-ts-client/         # TypeScript HTTP client generator
+│   ├── protoc-gen-ts-server/         # TypeScript HTTP server generator
 │   └── protoc-gen-openapiv3/         # OpenAPI spec generator
 ├── internal/                      # Internal packages
 │   ├── httpgen/                      # HTTP generation logic
 │   ├── clientgen/                    # Go HTTP client generation logic
+│   ├── tscommon/                     # Shared TypeScript type mapping
 │   ├── tsclientgen/                  # TypeScript HTTP client generation logic
+│   ├── tsservergen/                  # TypeScript HTTP server generation logic
 │   └── openapiv3/                    # OpenAPI generation logic
 ├── proto/                         # Protobuf definitions
 ├── http/                          # Generated HTTP annotations
@@ -395,6 +398,7 @@ make test
 go test ./internal/httpgen/...
 go test ./internal/openapiv3/...
 go test ./internal/tsclientgen/...
+go test ./internal/tsservergen/...
 
 # Run with coverage
 make test-coverage
@@ -403,6 +407,7 @@ make test-coverage
 UPDATE_GOLDEN=1 go test ./internal/httpgen/
 UPDATE_GOLDEN=1 go test ./internal/openapiv3/
 UPDATE_GOLDEN=1 go test ./internal/tsclientgen/
+UPDATE_GOLDEN=1 go test ./internal/tsservergen/
 ```
 
 ### Adding New Tests

README.md

@@ -32,6 +32,7 @@ This starts a working HTTP API with JSON endpoints and OpenAPI docs - all genera
 - **HTTP handlers** from protobuf services (JSON + binary support)
 - **Type-safe Go HTTP clients** with functional options pattern and per-call customization
 - **TypeScript HTTP clients** with full type safety, header helpers, and error handling
+- **TypeScript HTTP servers** using the Web Fetch API, framework-agnostic (Node, Deno, Bun, Cloudflare Workers)
 - **Mock server generation** with realistic field examples for rapid prototyping
 - **Automatic request validation** using protovalidate with buf.validate annotations
 - **HTTP header validation** with type checking and format validation (UUID, email, datetime)
@@ -109,6 +110,10 @@ const client = new UserServiceClient("http://localhost:8080", {
   apiKey: "your-api-key",
 });
 const user = await client.createUser({ name: "John", email: "john@example.com" });
+
+// TypeScript HTTP server (framework-agnostic, Web Fetch API)
+const routes = createUserServiceRoutes(handler);
+// Wire into any framework: Bun.serve, Deno.serve, Express, Hono, etc.
 ```
 
 ## Quick setup
@@ -119,6 +124,7 @@ go install github.com/SebastienMelki/sebuf/cmd/protoc-gen-go-http@latest
 go install github.com/SebastienMelki/sebuf/cmd/protoc-gen-go-client@latest
 go install github.com/SebastienMelki/sebuf/cmd/protoc-gen-openapiv3@latest
 go install github.com/SebastienMelki/sebuf/cmd/protoc-gen-ts-client@latest
+go install github.com/SebastienMelki/sebuf/cmd/protoc-gen-ts-server@latest
 
 # Try the complete example
 cd examples/simple-api && make demo
@@ -136,6 +142,7 @@ cd examples/simple-api && make demo
 - **API documentation** - OpenAPI specs that never get out of sync
 - **Type-safe development** - Leverage protobuf's type system for HTTP APIs
 - **Client generation** - Generate Go and TypeScript clients directly from your protobuf definitions
+- **Server generation** - Generate TypeScript HTTP servers using the Web Fetch API
 
 ## Built on Great Tools
 

cmd/protoc-gen-ts-server/main.go

@@ -0,0 +1,18 @@
+package main
+
+import (
+	"google.golang.org/protobuf/compiler/protogen"
+	"google.golang.org/protobuf/types/pluginpb"
+
+	"github.com/SebastienMelki/sebuf/internal/tsservergen"
+)
+
+func main() {
+	options := protogen.Options{}
+
+	options.Run(func(plugin *protogen.Plugin) error {
+		plugin.SupportedFeatures = uint64(pluginpb.CodeGeneratorResponse_FEATURE_PROTO3_OPTIONAL)
+		gen := tsservergen.New(plugin)
+		return gen.Generate()
+	})
+}