OwlBoard/backend-data-contracts
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Ugrade generation steps to use bufv2, and Gitea Go package registry.

Browse Source
This commit is contained in:
Fred Boniface
2026-01-07 13:15:14 +00:00
parent 59e405d2c4
commit 7e2361015a
10 changed files with 64 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
README.md
View File

@@ -1,34 +1,37 @@
# data-contracts
# backend-data-contracts
This repository is the single source of truth for all Protocol Buffer (Protobuf) schema definitions used across the Rail Ingress and Processing microservices.
This repository is the single source of truth for all Protocol Buffer (Protobuf) schema definitions used across the Owlboard Rail Ingress and Processing microservices. It follows a **Contract-First** approach, where language-specific code (Go, TypeScript) is generated and distributed via private registries.
## Purpose
The Protobuf files defined here serve as the immutable data contract for:
1. **Message Queue Payloads:** Defining messages pushed to the Artemis queue (Go Process Service consumption).
2. **Database Schemas:** Defining the expected structure of documents in MongoDB (Go Process and TypeScript API service consumption).
3. **Cross-Service Communication:** Ensuring type-safe data exchange between all polyglot services (Go, TypeScript).
1. **Ingress Logic:** Ensuring the Node.js and Go inregrate properly by sharing types.
2. **Message Payloads:** Defining messages for cross-service communication.
3. **Persistence:** Defining the expected structure of documents in MongoDB for the Go processing services.
## Directory Structure and Artifacts
## Directory Structure
| Path | Description | Contents |
| :--- | :--- | :--- |
| `protos/rail/v1/` | **Source Code.** Contains all source `.proto` files. **Only these files reside on the `main` branch.** | `.proto` files |
| `ts/` | **Generated TypeScript/JavaScript code.** Used as the root for the NPM package publish. **Not committed to Git.** | `package.json`, generated `.js`, `.d.ts` |
| `go.mod` | Defines the Go Module path: `git.fjla.uk/owlboard/backend-data-contracts`. | Go Module definition |
| `proto/` | **Source of Truth.** Contains the Protobuf schema definitions. | `rail_backend/v1/*.proto` |
| `buf.yaml` | **Workspace Config.** Defines linting and breaking change rules (Buf v2). | Workspace settings |
| `buf.gen.yaml` | **Generation Config.** Defines how Go and TS code is built. | Plugin & Managed Mode settings |
| `gen/` | **Transient Output.** Generated code resides here during CI/CD. | `.pb.go`, `.js`, `.d.ts` (**Git Ignored**) |
## Code Generation and Publishing Workflow (Gitea Action)
## Code Generation and Publishing Workflow
The generation process is automated via a Gitea Action (`.gitea/workflows/generate_contracts.yml`), which runs when a change is pushed to a source `.proto` file.
The generation and release process is automated via Gitea Actions. It is triggered whenever a new **SemVer tag** (e.g., `v1.0.0`) is pushed to this repository.
The action performs the following steps:
1. Generates all Go and TypeScript/JavaScript artifacts.
2. **Go Artifacts:** Commits the generated `*.pb.go` files to a **new Git tag** (e.g., `v1.0.1`), ensuring the `main` branch remains clean.
3. **TypeScript Artifacts:** Packages the generated files and publishes the corresponding version (e.g., `1.0.1`) to the internal NPM registry.
1. **Validation:** `buf lint` ensures schemas follow best practices.
2. **Generation:** `buf generate` creates Go and TypeScript code using local plugins.
3. **TS Release:** Compiles `.ts` to `.js` and publishes to the Gitea NPM Registry as `@owlboard/backend-data-contracts`.
4. **Go Release:** Initializes a `go.mod`, zips the artifacts, and pushes them to the Gitea Go Package Registry.
### To Consume the Contract:
## To Consume the Contracts
| Language | Artifact | Consumption Method |
| :--- | :--- | :--- |
| **Go** | Source Code (`*.pb.go`) | **Requires a Git Tag.** Update your service's `go.mod` file to reference the desired tag: `git.fjla.uk/owlboard/backend-data-contracts v1.0.1`. |
| **TypeScript** | NPM Package | Update the version in your `package.json` file and install: `"@owlboard/contracts": "1.0.1"`. |
### 1. Go Services
Since the package is hosted in the Gitea Package Registry, you must configure your environment to use the Gitea instance as a proxy.
**Setup:**
```bash
export GOPROXY=[https://git.fjla.uk/api/packages/owlboard/go,https://proxy.golang.org,direct](https://git.fjla.uk/api/packages/owlboard/go,https://proxy.golang.org,direct)