139 lines
4.6 KiB
Markdown
139 lines
4.6 KiB
Markdown
# Yoresee Doc SDK Migration Design
|
|
|
|
## Goal
|
|
|
|
Publish the protobuf-generated dependencies as two independent repositories under
|
|
the `YoreseeDoc` Gitea organization and migrate the four services to consume
|
|
those repositories:
|
|
|
|
- `yoresee_doc_sdk_go` for Go protobuf and gRPC stubs.
|
|
- `yoresee_doc_sdk_node` for browser ESM/Connect RPC stubs and Node.js CommonJS
|
|
gRPC stubs.
|
|
|
|
The existing protobuf repository remains the single source of the `.proto`
|
|
contract.
|
|
|
|
## Scope
|
|
|
|
This is a dependency migration, not a code-generation or CI/CD redesign.
|
|
|
|
Included:
|
|
|
|
- Generate and commit Go, ESM, and CommonJS artifacts in the two SDK repos.
|
|
- Use the Gitea repositories as versioned service dependencies.
|
|
- Change service imports to the SDK package paths.
|
|
- Change the protobuf `go_package` to the canonical Go SDK module path.
|
|
- Add package documentation describing the generated outputs and source proto.
|
|
|
|
Explicitly unchanged:
|
|
|
|
- `deploy/script/gen_proto.sh`.
|
|
- Existing Dockerfiles and Docker Compose files.
|
|
- Existing local generated-code directories and their fallback generation.
|
|
- CI/CD workflow and registry setup.
|
|
|
|
The existing local generation may continue to produce unused compatibility
|
|
artifacts during builds. It is intentionally left in place for this migration.
|
|
|
|
## Public Package Contracts
|
|
|
|
### Go
|
|
|
|
The Go SDK module path is:
|
|
|
|
```text
|
|
git.yoresee.cc/YoreseeDoc/yoresee_doc_sdk_go
|
|
```
|
|
|
|
Generated files live at:
|
|
|
|
```text
|
|
yoresee_doc/v1/yoresee_doc.pb.go
|
|
yoresee_doc/v1/yoresee_doc_grpc.pb.go
|
|
```
|
|
|
|
The protobuf `go_package` is changed to:
|
|
|
|
```text
|
|
git.yoresee.cc/YoreseeDoc/yoresee_doc_sdk_go/yoresee_doc/v1;yoreseedocpb
|
|
```
|
|
|
|
The initial SDK release is `v0.1.0`. `backend` and `collab-go` pin this
|
|
version instead of depending on the moving `master` branch.
|
|
|
|
### Node.js
|
|
|
|
The package name is `@yoresee-doc/sdk-node`, installed from:
|
|
|
|
```text
|
|
git+ssh://git@git.yoresee.cc/YoreseeDoc/yoresee_doc_sdk_node.git#v0.1.0
|
|
```
|
|
|
|
Generated output is split by runtime:
|
|
|
|
```text
|
|
esm/yoresee_doc/v1/yoresee_doc_pb.js
|
|
esm/yoresee_doc/v1/yoresee_doc_connect.js
|
|
cjs/yoresee_doc/v1/yoresee_doc_pb.js
|
|
cjs/yoresee_doc/v1/yoresee_doc_grpc_pb.js
|
|
```
|
|
|
|
The package uses conditional exports and explicit `esm/*` and `cjs/*`
|
|
subpaths. The `cjs/` directory declares CommonJS module semantics so the
|
|
root package can remain ESM-compatible.
|
|
|
|
Service import contracts are:
|
|
|
|
- `frontend`: `@yoresee-doc/sdk-node/esm/yoresee_doc/v1/...`
|
|
- `collab`: `@yoresee-doc/sdk-node/cjs/yoresee_doc/v1/...`
|
|
|
|
Runtime dependencies for both generated formats are declared by the SDK:
|
|
`@bufbuild/protobuf`, `@connectrpc/connect`, `@grpc/grpc-js`, and
|
|
`google-protobuf`.
|
|
|
|
## Generation and Repository Boundaries
|
|
|
|
The generated files are committed to the SDK repositories because they are the
|
|
published dependency artifacts. The source proto remains in the existing
|
|
`proto` repository and is not duplicated into the SDK repositories.
|
|
|
|
Generation for this initial migration is performed from the checked-out proto
|
|
source using the existing installed toolchains. The migration does not alter
|
|
the existing project generation scripts. Each SDK README records the source
|
|
proto commit and the generator versions used for the artifacts.
|
|
|
|
## Service Migration
|
|
|
|
`backend` and `collab-go` replace local generated-package imports with the Go
|
|
SDK import path and add the pinned Gitea module dependency. The services set
|
|
`GOPRIVATE` in their build environment documentation where required by the
|
|
private module.
|
|
|
|
`frontend` and `collab` add the pinned Git dependency and replace aliases or
|
|
relative paths that point to local generated files with the Node SDK exports.
|
|
|
|
No service behavior or protobuf message/service definitions change.
|
|
|
|
## Verification
|
|
|
|
The implementation is accepted only after all of the following checks pass:
|
|
|
|
- Go SDK generated package compiles and its module resolves at `v0.1.0`.
|
|
- Node SDK can be installed from the Gitea tag and both module formats load.
|
|
- `backend` and `collab-go` compile with the remote SDK dependency.
|
|
- `frontend` production build resolves the ESM/Connect exports.
|
|
- `collab` can load the CJS protobuf and gRPC exports.
|
|
- SDK repositories have clean commits pushed to `master`, with `v0.1.0`
|
|
tags.
|
|
|
|
## Risks and Rollback
|
|
|
|
- Private Gitea dependencies require read access from developer and Docker/CI
|
|
environments. A failed authenticated fetch is an environment issue, not a
|
|
protobuf generation issue.
|
|
- The old local generation remains redundant and may continue to fail because
|
|
its existing buf templates are outside this migration scope.
|
|
- Rollback consists of reverting service dependency/import changes and the
|
|
protobuf `go_package` change; SDK repositories remain harmless additive
|
|
artifacts.
|