databuild/plans/webapp_v1/chunk-1-client-generation.md

Chunk 1: TypeScript Client Generation

Parent: Build Graph Dashboard
Next: Chunk 2: Hello World App

Overview

Generate TypeScript client code from the DataBuild protobuf definitions to provide type-safe API access for the dashboard.

Scope

In Scope

• Generate TypeScript interfaces from databuild.proto
• Create typed client for Build Graph Service HTTP API endpoints
• Set up Bazel rules for protobuf-to-TypeScript generation
• Implement simple custom protobuf-to-TypeScript tooling (if off-the-shelf solutions are complex)

Out of Scope

• Full protobuf runtime features (only need type definitions)
• Complex protobuf features (focus on basic message types)
• Client-side validation (rely on server-side validation)

Technical Approach

Proto Analysis

Key messages to generate TypeScript for:

• BuildEvent and related event types
• PartitionRef, JobLabel, GraphLabel
• BuildRequestStatus, PartitionStatus, JobStatus
• JobGraph, Task, JobConfig
• Service request/response types

Generated Client Structure

// Generated types
interface PartitionRef {
  str: string;
}

interface BuildStatusResponse {
  build_request_id: string;
  status: BuildRequestStatus;
  requested_partitions: string[];
  created_at: number;
  updated_at: number;
  events: BuildEventSummary[];
}

// Client class
class BuildGraphClient {
  constructor(baseUrl: string);
  
  async submitBuild(partitions: string[]): Promise<{build_request_id: string}>;
  async getBuildStatus(id: string): Promise<BuildStatusResponse>;
  async cancelBuild(id: string): Promise<{cancelled: boolean}>;
  async getPartitionStatus(ref: string): Promise<PartitionStatusResponse>;
  async getPartitionEvents(ref: string): Promise<BuildEventSummary[]>;
  async analyzeGraph(partitions: string[]): Promise<{job_graph: JobGraph}>;
}

Bazel Integration

• Create //databuild/client:typescript target
• Generate TypeScript files from .proto sources
• Ensure hermetic build process
• Output client code to databuild/client/typescript/

Implementation Strategy

1. Assess Off-the-Shelf Solutions

   • Quick evaluation of existing protobuf-to-TypeScript tools
   • If complex setup required, proceed with custom implementation

2. Custom Generator (if needed)

   • Simple Python/Rust script to parse proto and generate TypeScript
   • Focus only on message types and basic field mapping
   • No complex protobuf features needed

3. Bazel Rules

   • Create typescript_proto_library rule
   • Generate client code during build
   • Ensure proper dependency management

Deliverables

• TypeScript interfaces for all relevant protobuf messages
• Typed HTTP client for Build Graph Service endpoints
• Bazel rules for client generation
• Documentation for using the generated client

Success Criteria

• Generated TypeScript compiles without errors
• Client provides type safety for all API endpoints
• Bazel build integrates seamlessly
• Ready for use in Chunk 2 (Hello World App)

Testing

• Verify generated TypeScript compiles
• Test client against running Build Graph Service
• Validate type safety with TypeScript compiler