102 lines
No EOL
3.2 KiB
Markdown
102 lines
No EOL
3.2 KiB
Markdown
# Chunk 1: TypeScript Client Generation
|
|
|
|
**Parent:** [Build Graph Dashboard](../build-graph-dashboard.md)
|
|
**Next:** [Chunk 2: Hello World App](./chunk-2-hello-world-app.md)
|
|
|
|
## 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
|
|
```typescript
|
|
// 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 |