release: 3.0.0-beta.1 — adopt lib-commons Huma wrapper (breaking)

.github/workflows/pr-validation.yml

@@ -17,6 +17,9 @@ jobs:
   validate:
     uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-pr-validation.yml@v1.36.5
     with:
+      enforce_source_branches: true
+      allowed_source_branches: 'hotfix/*|release-candidate'
+      target_branches_for_source_check: 'main'
       pr_title_scopes: |
         manager
         worker

.github/workflows/release.yml

@@ -14,7 +14,7 @@ permissions:
 
 jobs:
   pipeline:
-    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-release.yml@v1.36.5
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/go-release.yml@v1.40.3
     with:
       enable_changelog: ${{ github.ref == 'refs/heads/main' }}
       release_single_app: true

CLAUDE.md

@@ -14,7 +14,7 @@ Lerian Fetcher is an enterprise data extraction platform that unifies access to
 ```bash
 make set-env              # Copy .env.example to .env for all components
 make generate-master-key  # Generate APP_ENC_KEY (REQUIRED before services start)
-make dev-setup            # Install tools (golangci-lint, swag, mockgen, gosec) + tidy
+make dev-setup            # Install tools (golangci-lint, mockgen, gosec) + tidy
 ```
 
 ### Build & Run
@@ -44,7 +44,8 @@ make lint           # golangci-lint with --fix (28 linters, max cyclomatic compl
 make format         # go fmt
 make tidy           # go mod tidy
 make sec            # gosec security analysis
-make generate-docs  # Regenerate Swagger docs (swag init)
+make generate-docs  # Regenerate the canonical Huma OpenAPI 3.1 specification
+make check-openapi  # Fail when the committed OpenAPI specification is stale
 ```
 
 ## Architecture
@@ -115,7 +116,7 @@ Async RabbitMQ consumer. Does NOT follow CQRS - uses a single `UseCase` struct i
 
 **CQRS services (Manager only):** Struct with `Execute()` method. Constructor `NewXxx(deps...)`. Dependencies are port interfaces, never concrete implementations.
 
-**HTTP handlers:** Thin handlers in `internal/adapters/http/in/` with Swagger annotations (swaggo). Extract org ID via `httpUtils.GetOrganizationID(c)`, product name from `X-Product-Name` header.
+**HTTP operations:** Typed Huma callbacks in `internal/adapters/http/in/huma_*.go`, registered through the single runtime/spec assembly. Preserve the request context installed by auth/tenant middleware and read the product name from the `X-Product-Name` header when required. Return errors through the lib-commons RFC 9457 problem model.
 
 **Error handling:** Use `pkg.ValidateBusinessError(constant.ErrXxx, "entityType", args...)` for business errors. Custom types in `pkg/errors.go` map to HTTP status codes.
 
@@ -165,19 +166,19 @@ Async RabbitMQ consumer. Does NOT follow CQRS - uses a single `UseCase` struct i
 | `components/manager/README.md` | Manager service (HTTP control plane, runs over the engine) |
 | `components/worker/README.md` | Worker service (async data plane, runs over the engine) |
 | `tests/e2e/README.md` | E2E test conventions, patterns, test catalog |
-| `components/manager/api/swagger.yaml` | OpenAPI specification |
+| `components/manager/api/openapi.yaml` | Canonical OpenAPI 3.1 specification |
 | `components/manager/api/requests.http` | API request examples for manual testing |
 | `.golangci.yml` | Full linter configuration (28 linters) |
 
 ## Common Workflows
 
 ### Adding a new API endpoint
 
-1. Create handler in `components/manager/internal/adapters/http/in/` with Swagger annotations
-2. Register route in the routes file
+1. Add the typed callback and operation metadata in the appropriate `components/manager/internal/adapters/http/in/huma_*.go` file
+2. Register the operation through the shared Huma assembly in `huma_operations.go`
 3. Create command or query service in `internal/services/command/` or `internal/services/query/`
 4. Wire dependencies in `internal/bootstrap/`
-5. Run `make generate-docs`
+5. Run `make generate-docs` and `make check-openapi`
 
 ### Adding a new database adapter
 

Makefile

@@ -146,7 +146,8 @@ help:
 	@echo ""
 	@echo ""
 	@echo "Documentation Commands:"
-	@echo "  make generate-docs               - Generate Swagger documentation"
+	@echo "  make generate-docs               - Generate the canonical Huma OpenAPI 3.1 specification"
+	@echo "  make check-openapi               - Fail when the committed OpenAPI specification is stale"
 	@echo ""
 	@echo ""
 	@echo "Test Suite Aliases:"
@@ -230,8 +231,8 @@ set-env:
 # Deterministic, non-live quality gate. Mirrors the Lerian CI pattern
 # (cf. plugin-br-bank-transfer) restricted to steps that need no Docker
 # daemon, no live infrastructure, and no GITHUB_TOKEN — so it runs the
-# same locally and in CI. Docker-bound steps (generate-docs, test-e2e,
-# test-chaos) stay available standalone and run in their own CI stages.
+# same locally and in CI. Docker-bound steps (test-e2e, test-chaos) stay
+# available standalone and run in their own CI stages.
 .PHONY: ci
 ci:
 	$(call print_title,Running full CI pipeline)
@@ -240,6 +241,7 @@ ci:
 	@$(MAKE) vet
 	@$(MAKE) lint
 	@$(MAKE) sec
+	@$(MAKE) check-openapi
 	@$(MAKE) test-unit
 	@echo "[ok] CI pipeline passed"
 
@@ -795,20 +797,21 @@ ps:
 
 .PHONY: generate-docs
 generate-docs:
-	$(call print_title,Generating Swagger API documentation)
-	@if ! command -v swag >/dev/null 2>&1; then \
-		echo "Installing swag..."; \
-		go install github.com/swaggo/swag/cmd/swag@latest; \
-	fi
-	@swag init -g ./components/manager/cmd/app/main.go -d ./ -o ./components/manager/api --parseDependency --parseInternal
-	@docker run --rm -v $(ROOT_DIR):/local --user $(shell id -u):$(shell id -g) openapitools/openapi-generator-cli:v5.1.1 generate -i /local/components/manager/api/swagger.json -g openapi-yaml -o /local/components/manager/api
-	@mv ./components/manager/api/openapi/openapi.yaml ./components/manager/api/openapi.yaml
-	@rm -rf ./components/manager/api/README.md ./components/manager/api/.openapi-generator* ./components/manager/api/openapi
-	@if [ -f "$(ROOT_DIR)/scripts/package.json" ]; then \
-		echo "Installing npm dependencies for validation..."; \
-		cd $(ROOT_DIR)/scripts && npm install > /dev/null; \
-	fi
-	@echo "[ok] Swagger API documentation generated successfully"
+	$(call print_title,Generating canonical Huma OpenAPI specification)
+	@go run ./components/manager/cmd/huma-spec -output ./components/manager/api/openapi.yaml
+	@echo "[ok] OpenAPI 3.1 specification generated successfully"
+
+.PHONY: check-openapi
+check-openapi:
+	$(call print_title,Checking committed OpenAPI specification)
+	@tmp=$$(mktemp); \
+	trap 'rm -f "$$tmp"' EXIT; \
+	go run ./components/manager/cmd/huma-spec -output "$$tmp" || { echo "OpenAPI specification generation failed"; exit 1; }; \
+	cmp -s "$$tmp" ./components/manager/api/openapi.yaml || { \
+		echo "OpenAPI specification is stale; run 'make generate-docs'"; \
+		exit 1; \
+	}
+	@echo "[ok] Committed OpenAPI specification is current"
 
 #-------------------------------------------------------
 # Developer Helper Commands
@@ -822,10 +825,6 @@ dev-setup:
 		echo "Installing golangci-lint..."; \
 		go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest; \
 	fi
-	@if ! command -v swag >/dev/null 2>&1; then \
-		echo "Installing swag..."; \
-		go install github.com/swaggo/swag/cmd/swag@latest; \
-	fi
 	@if ! command -v mockgen >/dev/null 2>&1; then \
 		echo "Installing mockgen..."; \
 		go install go.uber.org/mock/mockgen@latest; \
@@ -1020,6 +1019,3 @@ generate-master-key: ## Generate a new cryptographically secure master key
 	echo "" && \
 	echo "IMPORTANT: Store this key securely. It cannot be recovered if lost." && \
 	echo "Add to your environment as APP_ENC_KEY."
-
-
-

README.md

@@ -232,14 +232,15 @@ Lerian Fetcher is built as a cloud-native platform following Hexagonal Architect
 | `GET` | `/health` | Liveness check |
 | `GET` | `/readyz` | Readiness check — parallel dependency probes (MongoDB, RabbitMQ, Redis; S3 on Worker), returns 503 while draining on SIGTERM |
 | `GET` | `/version` | Version info |
-| `GET` | `/swagger/*` | Swagger UI |
+| `GET` | `/swagger/docs` | Scalar API reference (`SWAGGER_ENABLED=true`) |
+| `GET` | `/swagger/openapi.{json,yaml}` | OpenAPI 3.1 contract (`SWAGGER_ENABLED=true`) |
 
 ### API Reference & Testing
 
 For hands-on API exploration and testing scenarios, the following resources are available:
 
 - **[`components/manager/api/requests.http`](components/manager/api/requests.http)**: Ready-to-use HTTP request examples covering all API endpoints — useful for quick testing with VS Code REST Client, IntelliJ, or similar tools.
-- **[`components/manager/api/swagger.yaml`](components/manager/api/swagger.yaml)**: Full OpenAPI specification for the Manager API, which can be imported into Postman, Insomnia, or any OpenAPI-compatible tool.
+- **[`components/manager/api/openapi.yaml`](components/manager/api/openapi.yaml)**: Canonical OpenAPI 3.1 specification for the Manager API, generated from the same Huma assembly used at runtime.
 - **[`tests/e2e/`](tests/e2e/)**: End-to-end test suite covering connection management, data extraction across all supported databases, filtering, multi-datasource/multi-schema scenarios, schema validation, and error handling. These tests serve as practical usage examples and can be referenced to understand expected behaviors and edge cases.
 
 ### Technical Highlights
@@ -315,7 +316,7 @@ Single-tenant deployments emit with stable tenant ID `single-tenant`; multi-tena
 
 5. **Access the API:**
    - REST API: `http://localhost:4006`
-   - Swagger UI: `http://localhost:4006/swagger/index.html`
+   - Scalar API reference (when enabled): `http://localhost:4006/swagger/docs`
    - RabbitMQ Management: `http://localhost:3008`
 
 ### Security

components/manager/.env.example

@@ -38,14 +38,7 @@ RABBITMQ_HEALTH_CHECK_URL=http://${RABBITMQ_HOST}:${RABBITMQ_PORT_HOST}
 #RABBITMQ_TLS=false
 
 # SWAGGER
-SWAGGER_TITLE='Fetcher'
-SWAGGER_DESCRIPTION='Documentation for fetcher'
-SWAGGER_VERSION=${VERSION}
-SWAGGER_HOST=${SERVER_ADDRESS}
-SWAGGER_BASE_PATH=/
-SWAGGER_SCHEMES=http
-SWAGGER_LEFT_DELIM={{
-SWAGGER_RIGHT_DELIM=}}
+SWAGGER_ENABLED=false
 
 # AUTHORIZATION
 PLUGIN_AUTH_ENABLED=false
@@ -87,6 +80,13 @@ MULTI_TENANT_ENABLED=false
 #MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD=5
 #MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC=30
 #MULTI_TENANT_SERVICE_API_KEY=
+# Per-service tenant-manager API keys (optional). Scheme:
+#   MULTI_TENANT_SERVICE_API_KEY_<SERVICE>  where <SERVICE> = the service name, hyphens->underscores, upper-cased.
+# When set, the resolver authenticates that service's tenant-config lookups with the matching key;
+# falls back to MULTI_TENANT_SERVICE_API_KEY when a per-service key is absent.
+# Adding a new service is env-only (no code change). Two env vars normalizing to the same token fail fast at startup.
+#MULTI_TENANT_SERVICE_API_KEY_LEDGER=
+#MULTI_TENANT_SERVICE_API_KEY_PLUGIN_CRM=
 #MULTI_TENANT_CACHE_TTL_SEC=120
 #MULTI_TENANT_TIMEOUT=30
 #MULTI_TENANT_ALLOW_INSECURE_HTTP=false

components/manager/Dockerfile

@@ -1,6 +1,6 @@
 # syntax=docker/dockerfile:1.4 
 
-FROM golang:1.26.4-alpine AS builder
+FROM golang:1.26.5-alpine AS builder
 
 # Install required packages: git is needed for private modules
 RUN apk add --no-cache git

components/manager/Makefile

@@ -47,7 +47,8 @@ info:
 	@echo "                                                                                                                         "
 	@echo "## App commands:"
 	@echo "                                                                                                                         "
-	@echo "  COMMAND=\"generate-docs\" 						  Generates Swagger API documentation and an OpenAPI Specification."
+	@echo "  COMMAND=\"generate-docs\" 						  Generates the canonical Huma OpenAPI 3.1 specification."
+	@echo "  COMMAND=\"check-openapi\" 						  Fails when the committed OpenAPI specification is stale."
 	@echo "                                                                                                                                       "
 	@echo "                                                                                                                                       "
 
@@ -85,10 +86,11 @@ ps:
 
 .PHONY: generate-docs
 generate-docs:
-	@swag init -g ./cmd/app/main.go -d ./ -o ./api --parseDependency --parseInternal
-	@docker run --rm -v $(pwd):/local --user $(shell id -u):$(shell id -g) openapitools/openapi-generator-cli:v5.1.1 generate -i ./manager/api/swagger.json -g openapi-yaml -o ./manager/api
-	@mv ./api/openapi/openapi.yaml ./api/openapi.yaml
-	@rm -rf ./api/README.md ./api/.openapi-generator* ./api/openapi
+	@$(MAKE) -C ../.. generate-docs
+
+.PHONY: check-openapi
+check-openapi:
+	@$(MAKE) -C ../.. check-openapi
 
 .PHONY: setup-git-hooks
 setup-git-hooks:
@@ -149,4 +151,4 @@ test:
 set-env:
 	@echo "$(BLUE)Setting up environment files...$(NC)"
 	cp -r ./.env.example ./.env
-	@echo "$(BLUE)Environment files created successfully$(NC)"
+	@echo "$(BLUE)Environment files created successfully$(NC)"

components/manager/README.md

@@ -2,7 +2,7 @@
 
 The Manager is the Fetcher HTTP API server. It runs the synchronous control plane: connection CRUD, schema discovery and validation, connection testing, idempotency, rate limiting, license enforcement, and job dispatch onto RabbitMQ. The Worker does the actual extraction asynchronously.
 
-The Manager is built on [Fiber](https://gofiber.io) and serves on port `4006`. It follows Hexagonal Architecture with CQRS: commands mutate state, queries read it, and both depend only on port interfaces.
+The Manager is built on [Fiber](https://gofiber.io) with typed [Huma](https://huma.rocks) operations and serves on port `4006`. The same assembly drives runtime routing and the canonical OpenAPI 3.1 contract. It follows Hexagonal Architecture with CQRS: commands mutate state, queries read it, and both depend only on port interfaces.
 
 ## Table of Contents
 
@@ -37,7 +37,7 @@ The Manager wires **two** engine instances, each a focused authority:
 
 ```mermaid
 graph TB
-    subgraph Manager["Manager (Fiber, port 4006)"]
+    subgraph Manager["Manager (Fiber + Huma, port 4006)"]
         Handlers["HTTP handlers\ninternal/adapters/http/in"]
         CmdQ["CQRS commands & queries\ninternal/services"]
         ConnEng["connection engine\nbootstrap/connection_engine.go"]
@@ -121,7 +121,7 @@ graph LR
     Qry -. delegates rules .-> Engine
 ```
 
-- **Inbound adapters** (`internal/adapters/http/in/`) are thin Fiber handlers with Swagger annotations. They extract the organization ID via `httpUtils.GetOrganizationID(c)` and the product name from the `X-Product-Name` header, then call a service.
+- **Inbound adapters** (`internal/adapters/http/in/`) expose typed Huma callbacks over Fiber. Operation metadata, request/response schemas, and RFC 9457 errors come from the same assembly used to generate OpenAPI 3.1. The callbacks preserve the auth/tenant request context, read the `X-Product-Name` header when required, then call a service.
 - **Commands** (`internal/services/command/`) handle connection Create, Update, and Delete, plus job creation (`CreateFetcherJob`) and connection assignment (`AssignConnection`).
 - **Queries** (`internal/services/query/`) handle Get, List, Test, and Validate.
 - **Bootstrap** (`internal/bootstrap/`) wires dependencies, including the two engines, and holds configuration.
@@ -191,14 +191,14 @@ License enforcement is **fail-closed**: when `DEPLOYMENT_MODE` is not `local`, t
 | Path | Contents |
 |------|----------|
 | `cmd/app/main.go` | Entry point |
-| `internal/adapters/http/in/` | Fiber HTTP handlers (with Swagger annotations) |
+| `internal/adapters/http/in/` | Typed Huma operations and Fiber integration |
 | `internal/services/command/` | CQRS commands (Create, Update, Delete) |
 | `internal/services/query/` | CQRS queries (Get, List, Test, Validate) |
 | `internal/adapters/cache/` | Redis schema cache adapter |
 | `internal/bootstrap/` | Dependency injection, config, and engine wiring |
 | `internal/bootstrap/connection_engine.go` | Connection engine wiring |
 | `internal/bootstrap/schema_engine.go` | Schema engine wiring |
-| `api/swagger.yaml` | OpenAPI specification |
+| `api/openapi.yaml` | Canonical OpenAPI 3.1 specification |
 | `api/requests.http` | Manual API request examples |
 
 ## Configuration
@@ -218,3 +218,5 @@ make generate-master-key
 | other non-`local` | Enforced (fail-closed) | — |
 
 See `internal/bootstrap/config.go` for the full configuration surface and `../../README.md` for the project-wide quick start.
+
+Set `SWAGGER_ENABLED=true` to expose the Scalar reference at `/swagger/docs` and the OpenAPI 3.1 contract at `/swagger/openapi.json` or `/swagger/openapi.yaml`. The routes are absent when the flag is disabled.