[meling]

Closes #349. Stacked on #379 (generated service clients) in a gh stack; the base moves when #379 merges.

Important

Part of the v0.13 changes with #379; merge after #379, or together with it.

Problem

A proto file could hold only one service, and two proto files could not share a Go package.
The generator rejected the first case.
In the second case, every generated file repeated the Config, Node, and CorrectableX declarations, so the package did not compile.

#379 already moved each RPC onto per-service client interfaces, so two services with the same RPC name no longer collide.
This PR removes the remaining blockers.

Changes

1. Several services per file (B1 in feat: support multiple services per proto file and per Go package #349): the one-service check is gone, and the options of every service are validated.
2. Name checks across the package: the generated names of each service are checked against the messages, enums, enum values, and oneof wrappers of every file in the Go package, and against the names of every other service in the same protoc run.
   The names of a service are the interface, constructor, and struct of each client that it has (SClient, NewSClient, sClient, and SNodeClient, NewSNodeClient, sNodeClient), and SServer and RegisterSServer.
   An error names the file that declares the message and the service that generates the name, for example: other.proto: contains message ReservedClient, which is the Gorums identifier generated for service Reserved (failing.proto).
   For a plain gRPC service in an imported file, the check reserves the node client names, not the names that protoc-gen-go-grpc generates; the doc comment of checkReservedIdents says so.
3. Static aliases (Config, ID, Node, Correctable) in one gorums.pb.go per Go package (B2, option (ii) in feat: support multiple services per proto file and per Go package #349): every protoc run that generates Gorums code for a package writes the same gorums.pb.go next to its X_gorums.pb.go files, so separate runs and mixed packages with plain gRPC services work.
   pb.Config, pb.ID, and pb.Node stay as they are, and these names stay reserved.
   The file content depends only on the Go package name, so the runs never disagree.
   A proto file named gorums.proto in the same package is rejected, because protoc-gen-go would write the same file.
4. One generic Correctable alias (B3; master no longer generates AsyncX aliases): type Correctable[Resp any] = gorums.Correctable[Resp] in gorums.pb.go replaces the per-type CorrectableX aliases.
   The generator no longer needs to decide which file declares an alias, and separate protoc runs work in every case.
   Correctable is now a reserved name, like Config, ID, and Node.
5. Docs: a "Several Services" section in the user guide, a paragraph on several services in the package doc, the gorums.pb.go file in the user and dev guides, and a migration note for the CorrectableX aliases.
6. Generated code, in the last commit.

flowchart LR
  cfg["gorums.Config (one, shared)"]
  alpha["pb.NewAlphaClient(cfg)<br/>.Heartbeat()"]
  beta["pb.NewBetaClient(cfg)<br/>.Heartbeat() .Write()"]
  node["pb.NewAlphaNodeClient(node)<br/>.Read()"]
  srv["gorums.Server<br/>RegisterAlphaServer + RegisterBetaServer"]
  alpha --> cfg
  beta --> cfg
  node -. "one node of cfg" .-> cfg
  cfg -- "pkg.Alpha.Heartbeat / pkg.Beta.Heartbeat" --> srv

Loading

Breaking changes

• The per-type CorrectableX aliases are gone.
  Replace pb.CorrectableX with *pb.Correctable[*pb.X].
  doc/migration-v2-to-v3.md describes the change.
• A proto message or enum named Correctable is now a generator error.

pb.Config, pb.ID, and pb.Node keep their names.
Regenerating moves these aliases from each X_gorums.pb.go into the new gorums.pb.go.
Some proto files whose generated code did not compile now get a clear generator error instead.

Notes

• Proto files of one Go package may be compiled in separate protoc runs, in any order.
• After removing the last Gorums file of a package, delete its stale gorums.pb.go.
• The first four commits do not pass go test ./..., because internal/tests/multiservice gets its generated code later. Some commits also come before the commit that regenerates their output. The tip passes.

Testing

• Generator: a multi-service fixture with golden output (two services, both with Heartbeat); failing cases for duplicate names within a file, across files, against server names, against a message in another file, against a message named Correctable (in the same file and in an imported file), for a client name shared by two services (FooNode with a quorum call and Foo with a remote call), and for options of a service that is not the first.
• TestGeneratePackageFiles compiles two proto files in one Go package, also with a shared response type and the same RPC name in both, checks that both outputs exist, and checks which Go packages get a gorums.pb.go file (also with a messages-only first file, an imported file first, and two Go packages in one run). TestGeneratePackageFilesSeparateRuns compiles the output of two separate runs, in both orders, as one package, also without an import relation and with a plain gRPC import.
• TestMultiServiceSharedConfig registers two services on one server and calls both through one gorums.Config (and one node client); each reply shows that it reached its own service.
• go test ./... in the root, examples, and benchkit modules, with and without -tags=integration; make goplscheck, make modernize, and golangci-lint are clean.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

[meling]

One alias-deduplication issue reproduced; details inline. The existing test suites pass in the root, examples, and benchkit modules. The nested-type naming issue reported on #379 also persists at this tip.

[meling]

Restacked on the new #379 tip, which now generates two client interfaces per service (see the #308 design update). The branch was force-pushed.

• The name checks cover the interface, constructor, and unexported struct of each client that a service generates, plus its server names.
• Six commits that only made sense with node-argument calls and the helper methods are dropped.
• The docs describe several services with the two-interface design.
• One open point: for a plain gRPC service in an imported file, Gorums reserves the node client names (SNodeClient, NewSNodeClient, sNodeClient), but protoc-gen-go-grpc generates SClient, NewSClient, and sClient. A clash with those shows up only when the package compiles. The docs say this; the code is unchanged. Checking the gRPC names too would reserve more names, so I left it for you to decide.

[meling]

Restacked on the updated #379 (review fixes: unexported client names such as tlsNodeClient, InvalidArgument for ErrNoNode, shorter dev guide). The branch was force-pushed.

• The detailed name-check paragraphs of the dev guide are removed, as in the gengorums: generate service clients #379 review. The rules are now in the doc comment of checkReservedIdents, including the plain gRPC service note.
• Generated files are fresh at the tip, and the tests pass with and without -tags=integration.

[meling]

Reviewed the current tip, 722fea2, against #379's ef8e0df.
I found no additional actionable defects in this PR's incremental changes.

One inherited issue remains: a protobuf oneof wrapper can collide with the new unexported client struct, and generation succeeds before the Go package fails to compile.
The reproducer and finding are in the review on #379, so I have not duplicated the inline finding here.
The separate client/Correctable-alias collision reported there is already rejected by this PR's packageIdents check.

The earlier response-type alias collision and mixed gRPC package concerns are addressed in the current source and covered by passing generator tests.
Validation: go test ./... passes in the root, examples, and benchkit modules.