Add unit tests for RabbitMq and Udp transport servers and clients
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- Implemented comprehensive unit tests for RabbitMqTransportServer, covering constructor, disposal, connection management, event handlers, and exception handling. - Added configuration tests for RabbitMqTransportServer to validate SSL, durable queues, auto-recovery, and custom virtual host options. - Created unit tests for UdpFrameProtocol, including frame parsing and serialization, header size validation, and round-trip data preservation. - Developed tests for UdpTransportClient, focusing on connection handling, event subscriptions, and exception scenarios. - Established tests for UdpTransportServer, ensuring proper start/stop behavior, connection state management, and event handling. - Included tests for UdpTransportOptions to verify default values and modification capabilities. - Enhanced service registration tests for Udp transport services in the dependency injection container.
This commit is contained in:
master
292
docs/contracts/api-governance-baseline.md
Normal file
292
docs/contracts/api-governance-baseline.md
Normal file
@@ -0,0 +1,292 @@
|
||||
# CONTRACT-API-GOVERNANCE-BASELINE-012: Aggregate OpenAPI Spec & SDK Generation
|
||||
|
||||
> **Status:** Published
|
||||
> **Version:** 1.0.0
|
||||
> **Published:** 2025-12-05
|
||||
> **Owners:** API Governance Guild, SDK Generator Guild
|
||||
> **Unblocks:** SDKGEN-63-001, SDKGEN-63-002, SDKGEN-63-003, SDKGEN-63-004, SDKGEN-64-001, SDKGEN-64-002
|
||||
|
||||
## Overview
|
||||
|
||||
This contract defines the aggregate OpenAPI specification freeze process, versioning rules, and SHA256 commitment mechanism that enables deterministic SDK generation across TypeScript, Python, Go, and Java targets.
|
||||
|
||||
## Aggregate Specification
|
||||
|
||||
### Source Location
|
||||
|
||||
```
|
||||
src/Api/StellaOps.Api.OpenApi/stella.yaml
|
||||
```
|
||||
|
||||
### Composition Process
|
||||
|
||||
The aggregate spec is generated by `compose.mjs` from per-service specs:
|
||||
|
||||
| Service | Source Spec | Tag Prefix |
|
||||
|---------|-------------|------------|
|
||||
| Authority | `authority/openapi.yaml` | `authority.*` |
|
||||
| Export Center | `export-center/openapi.yaml` | `export.*` |
|
||||
| Graph | `graph/openapi.yaml` | `graph.*` |
|
||||
| Orchestrator | `orchestrator/openapi.yaml` | `orchestrator.*` |
|
||||
| Policy | `policy/openapi.yaml` | `policy.*` |
|
||||
| Scheduler | `scheduler/openapi.yaml` | `scheduler.*` |
|
||||
|
||||
### Current Version
|
||||
|
||||
```yaml
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: StellaOps Aggregate API
|
||||
version: 0.0.1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Freeze Process
|
||||
|
||||
### 1. Version Tagging
|
||||
|
||||
When freezing for SDK generation:
|
||||
|
||||
```bash
|
||||
# Compute SHA256 of aggregate spec
|
||||
sha256sum src/Api/StellaOps.Api.OpenApi/stella.yaml > stella.yaml.sha256
|
||||
|
||||
# Tag the commit
|
||||
git tag -a api/v0.1.0-alpha -m "API freeze for SDK Wave B generation"
|
||||
```
|
||||
|
||||
### 2. SHA256 Commitment
|
||||
|
||||
SDK generators must validate the spec hash before generation:
|
||||
|
||||
```bash
|
||||
# Environment variable for hash guard
|
||||
export STELLA_OAS_EXPECTED_SHA256="<sha256-hash>"
|
||||
|
||||
# Generator validates before running
|
||||
if [ "$(sha256sum stella.yaml | cut -d' ' -f1)" != "$STELLA_OAS_EXPECTED_SHA256" ]; then
|
||||
echo "ERROR: Spec hash mismatch - regenerate after spec freeze"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
### 3. Published Artifacts
|
||||
|
||||
On freeze, publish:
|
||||
|
||||
| Artifact | Location | Purpose |
|
||||
|----------|----------|---------|
|
||||
| Tagged spec | `api/v{version}` git tag | Version reference |
|
||||
| SHA256 file | `stella.yaml.sha256` | Hash verification |
|
||||
| Changelog | `CHANGELOG-api.md` | Breaking changes |
|
||||
|
||||
---
|
||||
|
||||
## SDK Generation Contract
|
||||
|
||||
### Generator Configuration
|
||||
|
||||
| Language | Config | Output |
|
||||
|----------|--------|--------|
|
||||
| TypeScript | `ts/config.yaml` | ESM/CJS with typed errors |
|
||||
| Python | `python/config.yaml` | sync/async clients, type hints |
|
||||
| Go | `go/config.yaml` | context-first API |
|
||||
| Java | `java/config.yaml` | builder pattern, OkHttp |
|
||||
|
||||
### Toolchain Lock
|
||||
|
||||
```yaml
|
||||
# toolchain.lock.yaml
|
||||
openapi-generator-cli: 7.4.0
|
||||
jdk: 21.0.1
|
||||
node: 22.x
|
||||
python: 3.11+
|
||||
go: 1.21+
|
||||
```
|
||||
|
||||
### Hash Guard Implementation
|
||||
|
||||
Each generator emits `.oas.sha256` for provenance:
|
||||
|
||||
```bash
|
||||
# Example: TypeScript generation
|
||||
echo "$STELLA_OAS_EXPECTED_SHA256 stella.yaml" > dist/.oas.sha256
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Versioning Rules
|
||||
|
||||
### Semantic Versioning
|
||||
|
||||
```
|
||||
MAJOR.MINOR.PATCH[-PRERELEASE]
|
||||
|
||||
- MAJOR: Breaking API changes
|
||||
- MINOR: New endpoints/fields (backwards compatible)
|
||||
- PATCH: Bug fixes, documentation
|
||||
- PRERELEASE: alpha, beta, rc
|
||||
```
|
||||
|
||||
### Breaking Change Detection
|
||||
|
||||
```bash
|
||||
# Run API compatibility check
|
||||
npm run api:compat -- --old scripts/__fixtures__/api-compat/old.yaml \
|
||||
--new src/Api/StellaOps.Api.OpenApi/stella.yaml
|
||||
```
|
||||
|
||||
### Version Matrix
|
||||
|
||||
| API Version | SDK Versions | Status |
|
||||
|-------------|--------------|--------|
|
||||
| 0.0.1 | - | Current (unfrozen) |
|
||||
| 0.1.0-alpha | TS/Py/Go/Java alpha | Target freeze |
|
||||
|
||||
---
|
||||
|
||||
## Freeze Checklist
|
||||
|
||||
Before SDK generation can proceed:
|
||||
|
||||
- [ ] All per-service specs pass `npm run api:lint`
|
||||
- [ ] Aggregate composition succeeds (`node compose.mjs`)
|
||||
- [ ] Breaking change review completed
|
||||
- [ ] SHA256 computed and committed
|
||||
- [ ] Git tag created (`api/v{version}`)
|
||||
- [ ] Changelog entry added
|
||||
- [ ] SDK generator configs updated with hash
|
||||
|
||||
---
|
||||
|
||||
## Current Freeze Status
|
||||
|
||||
### Pending Actions
|
||||
|
||||
| Action | Owner | Due | Status |
|
||||
|--------|-------|-----|--------|
|
||||
| Compute SHA256 for stella.yaml | API Governance Guild | 2025-12-06 | TODO |
|
||||
| Create api/v0.1.0-alpha tag | API Governance Guild | 2025-12-06 | TODO |
|
||||
| Update SDKGEN configs with hash | SDK Generator Guild | 2025-12-06 | TODO |
|
||||
|
||||
### Immediate Unblock Path
|
||||
|
||||
To immediately unblock SDK generation:
|
||||
|
||||
```bash
|
||||
# 1. Compute current spec hash
|
||||
cd src/Api/StellaOps.Api.OpenApi
|
||||
SHA=$(sha256sum stella.yaml | cut -d' ' -f1)
|
||||
echo "Current SHA256: $SHA"
|
||||
|
||||
# 2. Create hash file
|
||||
echo "$SHA stella.yaml" > stella.yaml.sha256
|
||||
|
||||
# 3. Tag for SDK generation
|
||||
git add stella.yaml.sha256
|
||||
git commit -m "chore(api): freeze aggregate spec for SDK Wave B"
|
||||
git tag -a api/v0.1.0-alpha -m "API freeze for SDK generation"
|
||||
|
||||
# 4. Set environment for generators
|
||||
export STELLA_OAS_EXPECTED_SHA256="$SHA"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## SDK Generation Commands
|
||||
|
||||
Once freeze is complete:
|
||||
|
||||
```bash
|
||||
# TypeScript
|
||||
cd src/Sdk/StellaOps.Sdk.Generator/ts
|
||||
./generate-ts.sh
|
||||
|
||||
# Python
|
||||
cd ../python
|
||||
./generate-python.sh
|
||||
|
||||
# Go
|
||||
cd ../go
|
||||
./generate-go.sh
|
||||
|
||||
# Java
|
||||
cd ../java
|
||||
./generate-java.sh
|
||||
|
||||
# Run all smoke tests
|
||||
npm run sdk:smoke
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Governance
|
||||
|
||||
### Change Process
|
||||
|
||||
1. **Propose:** Open PR with spec changes
|
||||
2. **Review:** API Governance Guild reviews for breaking changes
|
||||
3. **Test:** Run `api:lint` and `api:compat`
|
||||
4. **Merge:** Merge to main
|
||||
5. **Freeze:** Tag and compute SHA256 when ready for SDK
|
||||
|
||||
### Stakeholders
|
||||
|
||||
- **API Governance Guild:** Spec ownership, breaking change review
|
||||
- **SDK Generator Guild:** Generation toolchain, language packs
|
||||
- **Platform Security:** Signing key provisioning (SDKREL-63-001)
|
||||
|
||||
---
|
||||
|
||||
## Signing Keys
|
||||
|
||||
### Development Key (Available Now)
|
||||
|
||||
A development signing key is available for staging/testing:
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `tools/cosign/cosign.dev.key` | Private key (password: `stellaops-dev`) |
|
||||
| `tools/cosign/cosign.dev.pub` | Public key for verification |
|
||||
|
||||
**Usage for SDK staging:**
|
||||
```bash
|
||||
# Set environment for SDK signing
|
||||
export COSIGN_KEY_FILE=tools/cosign/cosign.dev.key
|
||||
export COSIGN_PASSWORD=stellaops-dev
|
||||
export COSIGN_ALLOW_DEV_KEY=1
|
||||
|
||||
# Or use CI workflow with allow_dev_key=1
|
||||
```
|
||||
|
||||
### Production Keys (Pending)
|
||||
|
||||
Production signing requires:
|
||||
- Sovereign crypto key provisioning (Action #7)
|
||||
- `COSIGN_PRIVATE_KEY_B64` CI secret
|
||||
- Optional `COSIGN_PASSWORD` for encrypted keys
|
||||
|
||||
### Key Resolution Order
|
||||
|
||||
1. `COSIGN_KEY_FILE` environment variable
|
||||
2. `COSIGN_PRIVATE_KEY_B64` (decoded to temp file)
|
||||
3. `tools/cosign/cosign.key` (production drop-in)
|
||||
4. `tools/cosign/cosign.dev.key` (only if `COSIGN_ALLOW_DEV_KEY=1`)
|
||||
|
||||
---
|
||||
|
||||
## Reference
|
||||
|
||||
- Aggregate spec: `src/Api/StellaOps.Api.OpenApi/stella.yaml`
|
||||
- Composition script: `src/Api/StellaOps.Api.OpenApi/compose.mjs`
|
||||
- Toolchain lock: `src/Sdk/StellaOps.Sdk.Generator/TOOLCHAIN.md`
|
||||
- SDK generators: `src/Sdk/StellaOps.Sdk.Generator/{ts,python,go,java}/`
|
||||
|
||||
---
|
||||
|
||||
## Changelog
|
||||
|
||||
| Version | Date | Author | Changes |
|
||||
|---------|------|--------|---------|
|
||||
| 1.0.0 | 2025-12-05 | API Governance Guild | Initial contract |
|
||||
Reference in New Issue
Block a user