116 lines
No EOL
4 KiB
Markdown
116 lines
No EOL
4 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
|
|
|
|
### OpenAPI-Based Generation
|
|
Generate TypeScript client from OpenAPI specification automatically derived from Build Graph Service:
|
|
|
|
Key API endpoints to generate TypeScript client for:
|
|
- `POST /api/v1/builds` - Submit build request
|
|
- `GET /api/v1/builds/:id` - Get build status
|
|
- `DELETE /api/v1/builds/:id` - Cancel build request
|
|
- `GET /api/v1/partitions/:ref/status` - Get partition status
|
|
- `GET /api/v1/partitions/:ref/events` - Get partition events
|
|
- `POST /api/v1/analyze` - Analyze build graph
|
|
|
|
### Generated Client Structure
|
|
```typescript
|
|
// Generated types from OpenAPI spec
|
|
interface BuildRequest {
|
|
partitions: string[];
|
|
}
|
|
|
|
interface BuildStatusResponse {
|
|
build_request_id: string;
|
|
status: string;
|
|
requested_partitions: string[];
|
|
created_at: number;
|
|
updated_at: number;
|
|
events: BuildEventSummary[];
|
|
}
|
|
|
|
// Generated client class
|
|
class BuildGraphClient {
|
|
constructor(baseUrl: string);
|
|
|
|
async submitBuild(request: BuildRequest): 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(request: AnalyzeRequest): Promise<AnalyzeResponse>;
|
|
}
|
|
```
|
|
|
|
### Bazel Integration
|
|
- Create `//databuild/client:typescript` target
|
|
- Generate OpenAPI spec from Build Graph Service
|
|
- Use OpenAPI Generator to create TypeScript client
|
|
- Ensure hermetic build process
|
|
- Output client code to `databuild/client/typescript/`
|
|
|
|
## Implementation Strategy
|
|
|
|
1. **Add OpenAPI Generation to Service**
|
|
- Add `aide` dependency for OpenAPI spec generation
|
|
- Modify Axum service to use `aide::ApiRouter`
|
|
- Add JsonSchema derives to request/response types
|
|
- Create OpenAPI spec endpoint
|
|
|
|
2. **OpenAPI Spec Extraction**
|
|
- Create Bazel rule to run service and extract OpenAPI spec
|
|
- Save spec as build artifact (JSON/YAML)
|
|
|
|
3. **TypeScript Client Generation**
|
|
- Add OpenAPI Generator to Bazel build system
|
|
- Create Bazel rule to generate TypeScript client from spec
|
|
- Use `typescript-fetch` generator for modern fetch-based client
|
|
|
|
4. **Bazel Rules**
|
|
- Create `typescript_openapi_library` rule
|
|
- Generate client code during build
|
|
- Ensure proper dependency management
|
|
|
|
## Deliverables
|
|
|
|
- [ ] OpenAPI spec generation from Build Graph Service
|
|
- [ ] TypeScript interfaces for all API request/response types
|
|
- [ ] Typed HTTP client for Build Graph Service endpoints
|
|
- [ ] Bazel rules for automated client generation
|
|
- [ ] Documentation for using the generated client
|
|
|
|
## Success Criteria
|
|
|
|
- OpenAPI spec accurately reflects all service endpoints
|
|
- Generated TypeScript compiles without errors
|
|
- Client provides type safety for all API endpoints
|
|
- Bazel build integrates seamlessly and generates client automatically
|
|
- Ready for use in Chunk 2 (Hello World App)
|
|
|
|
## Testing
|
|
|
|
- Verify OpenAPI spec generation from service
|
|
- Verify generated TypeScript compiles
|
|
- Test client against running Build Graph Service
|
|
- Validate type safety with TypeScript compiler
|
|
- Ensure build process is hermetic and reproducible |