diff --git a/.gitea/workflows/release.yaml b/.gitea/workflows/release.yaml index c4188c2..85e31cd 100644 --- a/.gitea/workflows/release.yaml +++ b/.gitea/workflows/release.yaml @@ -17,7 +17,7 @@ jobs: id: get_version run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT - - uses: bufbuild/buf-setup-action@v1 + - uses: bufbuild/buf-setup-action@v1.5.0 - uses: actions/setup-go@v5 with: @@ -36,39 +36,36 @@ jobs: - name: Install TS-Proto Plugin run: | - npm install ts-proto + npm install ts-proto typescript echo "$PATH:$(pwd)/ts-proto" >> $GITHUB_PATH - name: Generate Code run: buf generate - - name: Publish TS + - name: Build and Publish TS working-directory: gen/ts run: | npm init -y + # Add a build script to the generated package.json jq '.name = "@owlboard/backend-data-contracts" | .version = "${{ steps.get_version.outputs.VERSION }}" | - .description = "Generated Protobuf types for data ingress services" | - .repository = { - "type": "git", - "url": "git+https://${{ github.server_url }}/${{ github.repository }}.git" - } | - .bugs = { - "url": "https://${{ github.server_url }}/${{ github.repository }}/issues" - } | - .homepage = "https://${{ github.server_url }}/${{ github.repository }}#readme"' \ + .main = "./dist/index.js" | + .types = "./dist/index.d.ts" | + .scripts.build = "tsc *.ts --declaration --esm --outDir dist/" | + .devDependencies.typescript = "^5.0.0"' \ package.json > temp.json && mv temp.json package.json + + npx tsc *.ts --declaration --esm --outDir dist/ --target es2022 --moduleResolution node npm publish env: NODE_AUTH_TOKEN: ${{ secrets.PACKAGE_PUSH }} - - name: Commit Generated Go + - name: Publish Go run: | - git config user.name "owlbot" - git config user.email "owlbot@owlboard.info" - git add gen/go/*.go - git commit -m "OwlBot: Generated go types for ${{ steps.get_version.outputs.VERSION }}" - git diff-index --quiet HEAD || git commit -m "OwlBot: Generated go types for ${{ steps.get_version.outputs.VERSION }}" - git push origin HEAD:refs/tags/${{ github.ref_name }} --force - env: - GITHUB_TOKEN: ${{ secrets.REPO_PUSH }} \ No newline at end of file + cd gen/go + go mod init git.fjla.uk/owlboard/backend-data-contracts + go mod tidy + zip -r ../../rail-backend-${{ steps.get_version.outputs.VERSION }}.zip . + curl --user "owlbot:${{ secrets.PACKAGE_PUSH }}" \ + --upload-file ../../rail-backend-${{ steps.get_version.outputs.VERSION }}.zip \ + https://${{ github.server_url }}/api/packages/owlboard/go/upload diff --git a/README.md b/README.md index db4bc06..c356722 100644 --- a/README.md +++ b/README.md @@ -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) \ No newline at end of file diff --git a/buf.gen.yaml b/buf.gen.yaml index 869c9bf..8203f07 100644 --- a/buf.gen.yaml +++ b/buf.gen.yaml @@ -1,10 +1,14 @@ -version: v1 +version: v2 +managed: + enabled: true + override: + - file_option: go_package_prefix + value: github.com/owlboard/backend-data-contracts plugins: - - plugin: go + - local: go out: gen/go opt: paths=source_relative - - plugin: ts-proto - path: ./node_modules/ts-proto/protoc-gen-ts_proto + - local: ./node_modules/ts-proto/protoc-gen-ts_proto out: gen/ts opt: - esModuleInterop=true diff --git a/buf.work.yaml b/buf.work.yaml deleted file mode 100644 index 2d3ee3a..0000000 --- a/buf.work.yaml +++ /dev/null @@ -1,4 +0,0 @@ -# buf.work.yaml -version: v1 -directories: - - protos \ No newline at end of file diff --git a/buf.yaml b/buf.yaml new file mode 100644 index 0000000..0de2cc6 --- /dev/null +++ b/buf.yaml @@ -0,0 +1,9 @@ +version: v2 +modules: + - path: protos +lint: + use: + - DEFAULT +breaking: + use: + - FILE \ No newline at end of file diff --git a/go.mod b/go.mod deleted file mode 100644 index f49f1f5..0000000 --- a/go.mod +++ /dev/null @@ -1,3 +0,0 @@ -module git.fjla.uk/owlboard/backend-data-contracts - -go 1.24.10 diff --git a/protos/rail/v1/common.proto b/protos/rail/v1/common.proto index f6f03d0..78b9bec 100644 --- a/protos/rail/v1/common.proto +++ b/protos/rail/v1/common.proto @@ -1,7 +1,6 @@ syntax = "proto3"; -package rail-backend.v1; -option go_package = "git.fjla.uk/owlboard/generated/go/rail-backend/v1"; +package rail_backend.v1; message Metadata { int64 push_to_queue_time = 1; diff --git a/protos/rail/v1/pis_schema.proto b/protos/rail/v1/pis_schema.proto index b0b0db9..e54505d 100644 --- a/protos/rail/v1/pis_schema.proto +++ b/protos/rail/v1/pis_schema.proto @@ -1,7 +1,6 @@ syntax = "proto3"; -package rail-backend.v1; -option go_package = "git.fjla.uk/owlboard/generated/go/rail-backend/v1"; +package rail_backend.v1; message PisReferenceList { repeated PisMapping entries = 1; diff --git a/protos/rail/v1/queue_message.proto b/protos/rail/v1/queue_message.proto index b2e492b..0ab6d04 100644 --- a/protos/rail/v1/queue_message.proto +++ b/protos/rail/v1/queue_message.proto @@ -1,11 +1,9 @@ syntax = "proto3"; -package rail-backend.v1; -option go_package = "git.fjla.uk/owlboard/generated/go/rail-backend/v1"; +package rail_backend.v1; - -import "rail-backend/v1/common.proto"; -import "rail-backend/v1/schedule_payload.proto"; +import "rail_backend/v1/common.proto"; +import "rail_backend/v1/schedule_payload.proto"; message IngressMessage { string correlation_id = 1; diff --git a/protos/rail/v1/schedule_payload.proto b/protos/rail/v1/schedule_payload.proto index 85e7aa5..c9088b9 100644 --- a/protos/rail/v1/schedule_payload.proto +++ b/protos/rail/v1/schedule_payload.proto @@ -1,7 +1,6 @@ syntax = "proto3"; -package rail-backend.v1; -option go_package = "git.fjla.uk/owlboard/generated/go/rail-backend/v1"; +package rail_backend.v1; enum SchedulePayloadType { VSTP_MESSAGE_TYPE_UNSPECIFIED = 0;