diff --git a/.vscode/gorums.txt b/.vscode/gorums.txt index d5468771c..b64c7039a 100644 --- a/.vscode/gorums.txt +++ b/.vscode/gorums.txt @@ -262,6 +262,7 @@ syncrq synctest TAILPID tcpstats +testdata testprotos testrace testutils @@ -285,6 +286,7 @@ underflowing unexport Unexported unicast +unicasts unmarshal unmarshaled unmarshaling diff --git a/benchkit/benchmark/benchmark_gorums.pb.go b/benchkit/benchmark/benchmark_gorums.pb.go index 59205cf62..a8394b10c 100644 --- a/benchkit/benchmark/benchmark_gorums.pb.go +++ b/benchkit/benchmark/benchmark_gorums.pb.go @@ -23,10 +23,13 @@ const ( // Reference imports to suppress errors if they are not otherwise used. var _ emptypb.Empty -// BenchmarkClient is the client API for the quorum calls and multicasts of -// the Benchmark service. Its calls execute on the configuration given to -// [NewBenchmarkClient]. If that configuration is empty, every call returns -// [gorums.ErrEmptyConfig]. +// BenchmarkClient is the client API for Benchmark quorum calls and +// multicasts on the client's configuration. If the configuration is empty, no +// message is sent and the call fails with [gorums.ErrEmptyConfig]. +// +// Benchmark is the gorums workload service benchmarked by benchkit. The +// measurement control plane (Start, Stop, ClockSync, Done) lives in benchkit's +// Control service; this service carries only the operations under test. type BenchmarkClient interface { // QuorumCall performs an echo quorum call on all servers. QuorumCall(ctx context.Context, in *Echo) *gorums.Call[*Echo, *Echo] @@ -69,7 +72,11 @@ func (c benchmarkClient) Multicast(ctx context.Context, in *TimedMsg) *gorums.On return gorumsimpl.Multicast(ctx, c.config, in, "benchmark.Benchmark.Multicast") } -// BenchmarkServer is the server-side API for the Benchmark Service +// BenchmarkServer is the server API for Benchmark. +// +// Benchmark is the gorums workload service benchmarked by benchkit. The +// measurement control plane (Start, Stop, ClockSync, Done) lives in benchkit's +// Control service; this service carries only the operations under test. type BenchmarkServer interface { QuorumCall(gorums.ServerContext, *Echo) (*Echo, error) SlowServer(gorums.ServerContext, *Echo) (*Echo, error) diff --git a/benchkit/control_gorums.pb.go b/benchkit/control_gorums.pb.go index 4c0741176..fe254b7ad 100644 --- a/benchkit/control_gorums.pb.go +++ b/benchkit/control_gorums.pb.go @@ -23,10 +23,14 @@ const ( // Reference imports to suppress errors if they are not otherwise used. var _ emptypb.Empty -// ControlClient is the client API for the quorum calls and multicasts of -// the Control service. Its calls execute on the configuration given to -// [NewControlClient]. If that configuration is empty, every call returns -// [gorums.ErrEmptyConfig]. +// ControlClient is the client API for Control quorum calls and +// multicasts on the client's configuration. If the configuration is empty, no +// message is sent and the call fails with [gorums.ErrEmptyConfig]. +// +// Control is the protocol-neutral measurement control plane. Any gorums-based +// protocol embeds it alongside its own workload service on the same listener. +// The four RPCs never reference a workload, so they are shared by every +// protocol that benchkit measures. type ControlClient interface { // Start resets the server-side op counter and Stats baseline. Start(ctx context.Context, in *StartRequest) *gorums.Call[*StartRequest, *StartResponse] @@ -83,7 +87,12 @@ func (c controlClient) Done(ctx context.Context, in *DoneRequest) *gorums.Oneway return gorumsimpl.Multicast(ctx, c.config, in, "benchkit.Control.Done") } -// ControlServer is the server-side API for the Control Service +// ControlServer is the server API for Control. +// +// Control is the protocol-neutral measurement control plane. Any gorums-based +// protocol embeds it alongside its own workload service on the same listener. +// The four RPCs never reference a workload, so they are shared by every +// protocol that benchkit measures. type ControlServer interface { Start(gorums.ServerContext, *StartRequest) (*StartResponse, error) Stop(gorums.ServerContext, *StopRequest) (*Result, error) diff --git a/cmd/protoc-gen-gorums/dev/zorums_client_gorums.pb.go b/cmd/protoc-gen-gorums/dev/zorums_client_gorums.pb.go index 3f06c0ce1..69d4f5455 100644 --- a/cmd/protoc-gen-gorums/dev/zorums_client_gorums.pb.go +++ b/cmd/protoc-gen-gorums/dev/zorums_client_gorums.pb.go @@ -23,10 +23,18 @@ const ( // Reference imports to suppress errors if they are not otherwise used. var _ emptypb.Empty -// ZorumsServiceClient is the client API for the quorum calls and multicasts of -// the ZorumsService service. Its calls execute on the configuration given to -// [NewZorumsServiceClient]. If that configuration is empty, every call returns -// [gorums.ErrEmptyConfig]. +// ZorumsServiceClient is the client API for ZorumsService quorum calls and +// multicasts on the client's configuration. If the configuration is empty, no +// message is sent and the call fails with [gorums.ErrEmptyConfig]. +// +// ZorumsService is not meant to be implemented. +// The zorums generated code is placed alongside Gorums static code files +// (without the zorums prefix) because they depend on the generated code. +// The generated code must pass compilation, but no further tests are performed. +// Other tests are provided to test the actual generated code. +// The RPCs in this service aims to test various uses of Gorums's +// options and call types, including imported message types and +// multiple RPCs reusing the same input and output types. type ZorumsServiceClient interface { // QuorumCall tests a plain quorum call. QuorumCall(ctx context.Context, in *Request) *gorums.Call[*Request, *Response] @@ -97,10 +105,18 @@ type zorumsServiceClient struct { config Config } -// ZorumsServiceNodeClient is the client API for the remote calls and unicasts -// of the ZorumsService service. Its calls execute on the node given to -// [NewZorumsServiceNodeClient]. If that node is nil, every call returns -// [gorums.ErrNoNode]. +// ZorumsServiceNodeClient is the client API for ZorumsService remote calls and +// unicasts on the client's node. If the node is nil, no message is sent and the +// call fails with [gorums.ErrNoNode]. +// +// ZorumsService is not meant to be implemented. +// The zorums generated code is placed alongside Gorums static code files +// (without the zorums prefix) because they depend on the generated code. +// The generated code must pass compilation, but no further tests are performed. +// Other tests are provided to test the actual generated code. +// The RPCs in this service aims to test various uses of Gorums's +// options and call types, including imported message types and +// multiple RPCs reusing the same input and output types. type ZorumsServiceNodeClient interface { // RemoteCall tests a method without a Gorums option. Gorums generates a // remote call for it, which replaces gRPC's unary RPC; no separate diff --git a/cmd/protoc-gen-gorums/dev/zorums_server_gorums.pb.go b/cmd/protoc-gen-gorums/dev/zorums_server_gorums.pb.go index b537bdbf1..0d7d59fcb 100644 --- a/cmd/protoc-gen-gorums/dev/zorums_server_gorums.pb.go +++ b/cmd/protoc-gen-gorums/dev/zorums_server_gorums.pb.go @@ -19,7 +19,16 @@ const ( _ = gorumsimpl.EnforceVersion(gorumsimpl.MaxVersion - 12) ) -// ZorumsServiceServer is the server-side API for the ZorumsService Service +// ZorumsServiceServer is the server API for ZorumsService. +// +// ZorumsService is not meant to be implemented. +// The zorums generated code is placed alongside Gorums static code files +// (without the zorums prefix) because they depend on the generated code. +// The generated code must pass compilation, but no further tests are performed. +// Other tests are provided to test the actual generated code. +// The RPCs in this service aims to test various uses of Gorums's +// options and call types, including imported message types and +// multiple RPCs reusing the same input and output types. type ZorumsServiceServer interface { RemoteCall(gorums.ServerContext, *Request) (*Response, error) QuorumCall(gorums.ServerContext, *Request) (*Response, error) diff --git a/cmd/protoc-gen-gorums/gengorums/template_client.go b/cmd/protoc-gen-gorums/gengorums/template_client.go index e4604c3cb..57684f188 100644 --- a/cmd/protoc-gen-gorums/gengorums/template_client.go +++ b/cmd/protoc-gen-gorums/gengorums/template_client.go @@ -106,11 +106,12 @@ func genClients(g *protogen.GeneratedFile, services []*protogen.Service) { var configClient = ` {{$errEmptyConfig := use "gorums.ErrEmptyConfig" .GenFile}} {{$service := .Service.GoName}} -// {{.Names.Interface}} is the client API for the quorum calls and multicasts of -// the {{$service}} service. Its calls execute on the configuration given to -// [{{.Names.Constructor}}]. If that configuration is empty, every call returns -// [{{$errEmptyConfig}}]. -type {{.Names.Interface}} interface { +{{$serviceComments := .Service.Comments.Leading}} +// {{.Names.Interface}} is the client API for {{$service}} quorum calls and +// multicasts on the client's configuration. If the configuration is empty, no +// message is sent and the call fails with [{{$errEmptyConfig}}]. +{{if ne $serviceComments ""}}// +{{$serviceComments}}{{end}}type {{.Names.Interface}} interface { {{.Methods}} } @@ -130,11 +131,12 @@ type {{.Names.Impl}} struct { var nodeClient = ` {{$errNoNode := use "gorums.ErrNoNode" .GenFile}} {{$service := .Service.GoName}} -// {{.Names.Interface}} is the client API for the remote calls and unicasts -// of the {{$service}} service. Its calls execute on the node given to -// [{{.Names.Constructor}}]. If that node is nil, every call returns -// [{{$errNoNode}}]. -type {{.Names.Interface}} interface { +{{$serviceComments := .Service.Comments.Leading}} +// {{.Names.Interface}} is the client API for {{$service}} remote calls and +// unicasts on the client's node. If the node is nil, no message is sent and the +// call fails with [{{$errNoNode}}]. +{{if ne $serviceComments ""}}// +{{$serviceComments}}{{end}}type {{.Names.Interface}} interface { {{.Methods}} } diff --git a/cmd/protoc-gen-gorums/gengorums/template_server.go b/cmd/protoc-gen-gorums/gengorums/template_server.go index 8f862b04a..b7252a950 100644 --- a/cmd/protoc-gen-gorums/gengorums/template_server.go +++ b/cmd/protoc-gen-gorums/gengorums/template_server.go @@ -53,8 +53,10 @@ var serverInterface = ` {{$genFile := .GenFile}} {{range .Services -}} {{$service := .Service.GoName}} -// {{.Names.Interface}} is the server-side API for the {{$service}} Service -type {{.Names.Interface}} interface { +{{$serviceComments := .Service.Comments.Leading}} +// {{.Names.Interface}} is the server API for {{$service}}. +{{if ne $serviceComments ""}}// +{{$serviceComments}}{{end}}type {{.Names.Interface}} interface { {{- range .Service.Methods}} {{- if isOneway .}} {{.GoName}}({{$context}}, *{{in $genFile .}}) diff --git a/examples/storage/proto/storage_gorums.pb.go b/examples/storage/proto/storage_gorums.pb.go index bb8dfbf44..3d06881da 100644 --- a/examples/storage/proto/storage_gorums.pb.go +++ b/examples/storage/proto/storage_gorums.pb.go @@ -23,10 +23,11 @@ const ( // Reference imports to suppress errors if they are not otherwise used. var _ emptypb.Empty -// StorageClient is the client API for the quorum calls and multicasts of -// the Storage service. Its calls execute on the configuration given to -// [NewStorageClient]. If that configuration is empty, every call returns -// [gorums.ErrEmptyConfig]. +// StorageClient is the client API for Storage quorum calls and +// multicasts on the client's configuration. If the configuration is empty, no +// message is sent and the call fails with [gorums.ErrEmptyConfig]. +// +// Storage is a simple key-value storage service type StorageClient interface { // WriteMulticast executes a Write multicast call on a configuration of nodes. // It does not wait for any responses. @@ -72,10 +73,11 @@ type storageClient struct { config Config } -// StorageNodeClient is the client API for the remote calls and unicasts -// of the Storage service. Its calls execute on the node given to -// [NewStorageNodeClient]. If that node is nil, every call returns -// [gorums.ErrNoNode]. +// StorageNodeClient is the client API for Storage remote calls and +// unicasts on the client's node. If the node is nil, no message is sent and the +// call fails with [gorums.ErrNoNode]. +// +// Storage is a simple key-value storage service type StorageNodeClient interface { // ReadRPC executes a Read RPC on a single node and // returns the value for the provided key. @@ -146,7 +148,9 @@ func (c storageClient) ReadCorrectable(ctx context.Context, in *ReadRequest) *go return gorumsimpl.QuorumCallStream[*ReadRequest, *ReadResponse](ctx, c.config, in, "proto.Storage.ReadCorrectable") } -// StorageServer is the server-side API for the Storage Service +// StorageServer is the server API for Storage. +// +// Storage is a simple key-value storage service type StorageServer interface { ReadRPC(gorums.ServerContext, *ReadRequest) (*ReadResponse, error) WriteRPC(gorums.ServerContext, *WriteRequest) (*WriteResponse, error) diff --git a/internal/testprotos/testdata/calltypes/importmsgs/importmsgs_gorums.pb.go.golden b/internal/testprotos/testdata/calltypes/importmsgs/importmsgs_gorums.pb.go.golden index 09bd59833..1b8cb8ec9 100644 --- a/internal/testprotos/testdata/calltypes/importmsgs/importmsgs_gorums.pb.go.golden +++ b/internal/testprotos/testdata/calltypes/importmsgs/importmsgs_gorums.pb.go.golden @@ -20,10 +20,9 @@ const ( _ = gorumsimpl.EnforceVersion(gorumsimpl.MaxVersion - 12) ) -// QuorumCallClient is the client API for the quorum calls and multicasts of -// the QuorumCall service. Its calls execute on the configuration given to -// [NewQuorumCallClient]. If that configuration is empty, every call returns -// [gorums.ErrEmptyConfig]. +// QuorumCallClient is the client API for QuorumCall quorum calls and +// multicasts on the client's configuration. If the configuration is empty, no +// message is sent and the call fails with [gorums.ErrEmptyConfig]. type QuorumCallClient interface { // QuorumCall executes a quorum call on the client's configuration. Use // terminal methods like Majority(), First(), or Threshold(n) to retrieve the @@ -49,7 +48,7 @@ func (c quorumCallClient) QuorumCall(ctx context.Context, in *msgs.Request) *gor return gorumsimpl.QuorumCall[*msgs.Request, *msgs.Response](ctx, c.config, in, "internal.testprotos.calltypes.importmsgs.QuorumCall.QuorumCall") } -// QuorumCallServer is the server-side API for the QuorumCall Service +// QuorumCallServer is the server API for QuorumCall. type QuorumCallServer interface { QuorumCall(gorums.ServerContext, *msgs.Request) (*msgs.Response, error) } diff --git a/internal/testprotos/testdata/calltypes/multicast/multicast_gorums.pb.go.golden b/internal/testprotos/testdata/calltypes/multicast/multicast_gorums.pb.go.golden index 10ed2f5c6..62d715a6f 100644 --- a/internal/testprotos/testdata/calltypes/multicast/multicast_gorums.pb.go.golden +++ b/internal/testprotos/testdata/calltypes/multicast/multicast_gorums.pb.go.golden @@ -23,10 +23,9 @@ const ( // Reference imports to suppress errors if they are not otherwise used. var _ emptypb.Empty -// MulticastClient is the client API for the quorum calls and multicasts of -// the Multicast service. Its calls execute on the configuration given to -// [NewMulticastClient]. If that configuration is empty, every call returns -// [gorums.ErrEmptyConfig]. +// MulticastClient is the client API for Multicast quorum calls and +// multicasts on the client's configuration. If the configuration is empty, no +// message is sent and the call fails with [gorums.ErrEmptyConfig]. type MulticastClient interface { // Multicast starts a one-way call on the client's configuration; no reply // is returned. Use gorums.MapRequest to send a different message to each node. @@ -59,7 +58,7 @@ func (c multicastClient) Multicast(ctx context.Context, in *Request) *gorums.One return gorumsimpl.Multicast(ctx, c.config, in, "internal.testprotos.calltypes.multicast.Multicast.Multicast") } -// MulticastServer is the server-side API for the Multicast Service +// MulticastServer is the server API for Multicast. type MulticastServer interface { Multicast(gorums.ServerContext, *Request) } diff --git a/internal/testprotos/testdata/calltypes/multiservice/multiservice_gorums.pb.go.golden b/internal/testprotos/testdata/calltypes/multiservice/multiservice_gorums.pb.go.golden index a806aa3cc..ca783b29b 100644 --- a/internal/testprotos/testdata/calltypes/multiservice/multiservice_gorums.pb.go.golden +++ b/internal/testprotos/testdata/calltypes/multiservice/multiservice_gorums.pb.go.golden @@ -23,10 +23,9 @@ const ( // Reference imports to suppress errors if they are not otherwise used. var _ emptypb.Empty -// AlphaClient is the client API for the quorum calls and multicasts of -// the Alpha service. Its calls execute on the configuration given to -// [NewAlphaClient]. If that configuration is empty, every call returns -// [gorums.ErrEmptyConfig]. +// AlphaClient is the client API for Alpha quorum calls and +// multicasts on the client's configuration. If the configuration is empty, no +// message is sent and the call fails with [gorums.ErrEmptyConfig]. type AlphaClient interface { // Heartbeat executes a quorum call on the client's configuration. Use // terminal methods like Majority(), First(), or Threshold(n) to retrieve the @@ -48,10 +47,9 @@ type alphaClient struct { config Config } -// AlphaNodeClient is the client API for the remote calls and unicasts -// of the Alpha service. Its calls execute on the node given to -// [NewAlphaNodeClient]. If that node is nil, every call returns -// [gorums.ErrNoNode]. +// AlphaNodeClient is the client API for Alpha remote calls and +// unicasts on the client's node. If the node is nil, no message is sent and the +// call fails with [gorums.ErrNoNode]. type AlphaNodeClient interface { // Read executes a remote call on the client's node and returns its // reply. @@ -73,10 +71,9 @@ type alphaNodeClient struct { node *Node } -// BetaClient is the client API for the quorum calls and multicasts of -// the Beta service. Its calls execute on the configuration given to -// [NewBetaClient]. If that configuration is empty, every call returns -// [gorums.ErrEmptyConfig]. +// BetaClient is the client API for Beta quorum calls and +// multicasts on the client's configuration. If the configuration is empty, no +// message is sent and the call fails with [gorums.ErrEmptyConfig]. type BetaClient interface { // Heartbeat executes a quorum call on the client's configuration. Use // terminal methods like Majority(), First(), or Threshold(n) to retrieve the @@ -130,13 +127,13 @@ func (c betaClient) Write(ctx context.Context, in *Request) *gorums.OnewayCall[* return gorumsimpl.Multicast(ctx, c.config, in, "internal.testprotos.calltypes.multiservice.Beta.Write") } -// AlphaServer is the server-side API for the Alpha Service +// AlphaServer is the server API for Alpha. type AlphaServer interface { Heartbeat(gorums.ServerContext, *Request) (*Response, error) Read(gorums.ServerContext, *Request) (*Response, error) } -// BetaServer is the server-side API for the Beta Service +// BetaServer is the server API for Beta. type BetaServer interface { Heartbeat(gorums.ServerContext, *Request) (*Response, error) Write(gorums.ServerContext, *Request) diff --git a/internal/testprotos/testdata/calltypes/quorumcall/quorumcall_gorums.pb.go.golden b/internal/testprotos/testdata/calltypes/quorumcall/quorumcall_gorums.pb.go.golden index eb8e9d5ac..22631f43f 100644 --- a/internal/testprotos/testdata/calltypes/quorumcall/quorumcall_gorums.pb.go.golden +++ b/internal/testprotos/testdata/calltypes/quorumcall/quorumcall_gorums.pb.go.golden @@ -19,10 +19,9 @@ const ( _ = gorumsimpl.EnforceVersion(gorumsimpl.MaxVersion - 12) ) -// QuorumCallClient is the client API for the quorum calls and multicasts of -// the QuorumCall service. Its calls execute on the configuration given to -// [NewQuorumCallClient]. If that configuration is empty, every call returns -// [gorums.ErrEmptyConfig]. +// QuorumCallClient is the client API for QuorumCall quorum calls and +// multicasts on the client's configuration. If the configuration is empty, no +// message is sent and the call fails with [gorums.ErrEmptyConfig]. type QuorumCallClient interface { // QuorumCall executes a quorum call on the client's configuration. Use // terminal methods like Majority(), First(), or Threshold(n) to retrieve the @@ -48,7 +47,7 @@ func (c quorumCallClient) QuorumCall(ctx context.Context, in *Request) *gorums.C return gorumsimpl.QuorumCall[*Request, *Response](ctx, c.config, in, "internal.testprotos.calltypes.quorumcall.QuorumCall.QuorumCall") } -// QuorumCallServer is the server-side API for the QuorumCall Service +// QuorumCallServer is the server API for QuorumCall. type QuorumCallServer interface { QuorumCall(gorums.ServerContext, *Request) (*Response, error) } diff --git a/internal/testprotos/testdata/clientnames/clientnames_gorums.pb.go.golden b/internal/testprotos/testdata/clientnames/clientnames_gorums.pb.go.golden index 1fb063a0c..5748fa428 100644 --- a/internal/testprotos/testdata/clientnames/clientnames_gorums.pb.go.golden +++ b/internal/testprotos/testdata/clientnames/clientnames_gorums.pb.go.golden @@ -23,10 +23,9 @@ const ( // Reference imports to suppress errors if they are not otherwise used. var _ emptypb.Empty -// ClientNamesClient is the client API for the quorum calls and multicasts of -// the ClientNames service. Its calls execute on the configuration given to -// [NewClientNamesClient]. If that configuration is empty, every call returns -// [gorums.ErrEmptyConfig]. +// ClientNamesClient is the client API for ClientNames quorum calls and +// multicasts on the client's configuration. If the configuration is empty, no +// message is sent and the call fails with [gorums.ErrEmptyConfig]. type ClientNamesClient interface { // Config is a quorum call. Config(ctx context.Context, in *Request) *gorums.Call[*Request, *Response] @@ -54,10 +53,9 @@ type clientNamesClient struct { config Config } -// ClientNamesNodeClient is the client API for the remote calls and unicasts -// of the ClientNames service. Its calls execute on the node given to -// [NewClientNamesNodeClient]. If that node is nil, every call returns -// [gorums.ErrNoNode]. +// ClientNamesNodeClient is the client API for ClientNames remote calls and +// unicasts on the client's node. If the node is nil, no message is sent and the +// call fails with [gorums.ErrNoNode]. type ClientNamesNodeClient interface { // Node is a remote call. Node(ctx context.Context, in *Request) (*Response, error) @@ -102,7 +100,7 @@ func (c clientNamesNodeClient) ForNode(ctx context.Context, in *Request) *gorums return gorumsimpl.Unicast(ctx, c.node, in, "internal.testprotos.clientnames.ClientNames.ForNode") } -// ClientNamesServer is the server-side API for the ClientNames Service +// ClientNamesServer is the server API for ClientNames. type ClientNamesServer interface { Config(gorums.ServerContext, *Request) (*Response, error) WithConfig(gorums.ServerContext, *Request) diff --git a/internal/testprotos/testdata/nodeonly/nodeonly_gorums.pb.go.golden b/internal/testprotos/testdata/nodeonly/nodeonly_gorums.pb.go.golden index 7c9583983..cafdbd9e5 100644 --- a/internal/testprotos/testdata/nodeonly/nodeonly_gorums.pb.go.golden +++ b/internal/testprotos/testdata/nodeonly/nodeonly_gorums.pb.go.golden @@ -23,10 +23,9 @@ const ( // Reference imports to suppress errors if they are not otherwise used. var _ emptypb.Empty -// NodeOnlyNodeClient is the client API for the remote calls and unicasts -// of the NodeOnly service. Its calls execute on the node given to -// [NewNodeOnlyNodeClient]. If that node is nil, every call returns -// [gorums.ErrNoNode]. +// NodeOnlyNodeClient is the client API for NodeOnly remote calls and +// unicasts on the client's node. If the node is nil, no message is sent and the +// call fails with [gorums.ErrNoNode]. type NodeOnlyNodeClient interface { // Read executes a remote call on the client's node and returns its // reply. @@ -72,7 +71,7 @@ func (c nodeOnlyNodeClient) Write(ctx context.Context, in *Request) *gorums.Onew return gorumsimpl.Unicast(ctx, c.node, in, "internal.testprotos.nodeonly.NodeOnly.Write") } -// NodeOnlyServer is the server-side API for the NodeOnly Service +// NodeOnlyServer is the server API for NodeOnly. type NodeOnlyServer interface { Read(gorums.ServerContext, *Request) (*Response, error) Write(gorums.ServerContext, *Request) diff --git a/internal/tests/correctable/correctable_gorums.pb.go b/internal/tests/correctable/correctable_gorums.pb.go index 3c636a97b..2719667e4 100644 --- a/internal/tests/correctable/correctable_gorums.pb.go +++ b/internal/tests/correctable/correctable_gorums.pb.go @@ -19,10 +19,9 @@ const ( _ = gorumsimpl.EnforceVersion(gorumsimpl.MaxVersion - 12) ) -// CorrectableTestClient is the client API for the quorum calls and multicasts of -// the CorrectableTest service. Its calls execute on the configuration given to -// [NewCorrectableTestClient]. If that configuration is empty, every call returns -// [gorums.ErrEmptyConfig]. +// CorrectableTestClient is the client API for CorrectableTest quorum calls and +// multicasts on the client's configuration. If the configuration is empty, no +// message is sent and the call fails with [gorums.ErrEmptyConfig]. type CorrectableTestClient interface { // Correctable executes a quorum call on the client's configuration. Use // terminal methods like Majority(), First(), or Threshold(n) to retrieve the @@ -63,7 +62,7 @@ func (c correctableTestClient) CorrectableStream(ctx context.Context, in *Reques return gorumsimpl.QuorumCallStream[*Request, *Response](ctx, c.config, in, "correctable.CorrectableTest.CorrectableStream") } -// CorrectableTestServer is the server-side API for the CorrectableTest Service +// CorrectableTestServer is the server API for CorrectableTest. type CorrectableTestServer interface { Correctable(gorums.ServerContext, *Request) (*Response, error) CorrectableStream(gorums.ServerContext, *Request, func(*Response)) diff --git a/internal/tests/metadata/metadata_gorums.pb.go b/internal/tests/metadata/metadata_gorums.pb.go index 3496c8462..bc98de149 100644 --- a/internal/tests/metadata/metadata_gorums.pb.go +++ b/internal/tests/metadata/metadata_gorums.pb.go @@ -20,10 +20,9 @@ const ( _ = gorumsimpl.EnforceVersion(gorumsimpl.MaxVersion - 12) ) -// MetadataTestNodeClient is the client API for the remote calls and unicasts -// of the MetadataTest service. Its calls execute on the node given to -// [NewMetadataTestNodeClient]. If that node is nil, every call returns -// [gorums.ErrNoNode]. +// MetadataTestNodeClient is the client API for MetadataTest remote calls and +// unicasts on the client's node. If the node is nil, no message is sent and the +// call fails with [gorums.ErrNoNode]. type MetadataTestNodeClient interface { // IDFromMD returns the 'id' field from the metadata. IDFromMD(ctx context.Context, in *emptypb.Empty) (*NodeID, error) @@ -51,7 +50,7 @@ func (c metadataTestNodeClient) WhatIP(ctx context.Context, in *emptypb.Empty) ( return gorumsimpl.RemoteCall[*emptypb.Empty, *IPAddr](ctx, c.node, in, "metadata.MetadataTest.WhatIP") } -// MetadataTestServer is the server-side API for the MetadataTest Service +// MetadataTestServer is the server API for MetadataTest. type MetadataTestServer interface { IDFromMD(gorums.ServerContext, *emptypb.Empty) (*NodeID, error) WhatIP(gorums.ServerContext, *emptypb.Empty) (*IPAddr, error) diff --git a/internal/tests/multiservice/multiservice_gorums.pb.go b/internal/tests/multiservice/multiservice_gorums.pb.go index 4afce4051..26f8cda09 100644 --- a/internal/tests/multiservice/multiservice_gorums.pb.go +++ b/internal/tests/multiservice/multiservice_gorums.pb.go @@ -19,10 +19,9 @@ const ( _ = gorumsimpl.EnforceVersion(gorumsimpl.MaxVersion - 12) ) -// AlphaClient is the client API for the quorum calls and multicasts of -// the Alpha service. Its calls execute on the configuration given to -// [NewAlphaClient]. If that configuration is empty, every call returns -// [gorums.ErrEmptyConfig]. +// AlphaClient is the client API for Alpha quorum calls and +// multicasts on the client's configuration. If the configuration is empty, no +// message is sent and the call fails with [gorums.ErrEmptyConfig]. type AlphaClient interface { // Heartbeat executes a quorum call on the client's configuration. Use // terminal methods like Majority(), First(), or Threshold(n) to retrieve the @@ -44,10 +43,9 @@ type alphaClient struct { config Config } -// AlphaNodeClient is the client API for the remote calls and unicasts -// of the Alpha service. Its calls execute on the node given to -// [NewAlphaNodeClient]. If that node is nil, every call returns -// [gorums.ErrNoNode]. +// AlphaNodeClient is the client API for Alpha remote calls and +// unicasts on the client's node. If the node is nil, no message is sent and the +// call fails with [gorums.ErrNoNode]. type AlphaNodeClient interface { // Read executes a remote call on the client's node and returns its // reply. @@ -69,10 +67,9 @@ type alphaNodeClient struct { node *Node } -// BetaClient is the client API for the quorum calls and multicasts of -// the Beta service. Its calls execute on the configuration given to -// [NewBetaClient]. If that configuration is empty, every call returns -// [gorums.ErrEmptyConfig]. +// BetaClient is the client API for Beta quorum calls and +// multicasts on the client's configuration. If the configuration is empty, no +// message is sent and the call fails with [gorums.ErrEmptyConfig]. type BetaClient interface { // Heartbeat executes a quorum call on the client's configuration. Use // terminal methods like Majority(), First(), or Threshold(n) to retrieve the @@ -119,13 +116,13 @@ func (c betaClient) Write(ctx context.Context, in *Request) *gorums.Call[*Reques return gorumsimpl.QuorumCall[*Request, *Response](ctx, c.config, in, "multiservice.Beta.Write") } -// AlphaServer is the server-side API for the Alpha Service +// AlphaServer is the server API for Alpha. type AlphaServer interface { Heartbeat(gorums.ServerContext, *Request) (*Response, error) Read(gorums.ServerContext, *Request) (*Response, error) } -// BetaServer is the server-side API for the Beta Service +// BetaServer is the server API for Beta. type BetaServer interface { Heartbeat(gorums.ServerContext, *Request) (*Response, error) Write(gorums.ServerContext, *Request) (*Response, error) diff --git a/internal/tests/oneway/oneway_gorums.pb.go b/internal/tests/oneway/oneway_gorums.pb.go index f21e6fc00..90ce5bb57 100644 --- a/internal/tests/oneway/oneway_gorums.pb.go +++ b/internal/tests/oneway/oneway_gorums.pb.go @@ -23,10 +23,9 @@ const ( // Reference imports to suppress errors if they are not otherwise used. var _ emptypb.Empty -// OnewayTestClient is the client API for the quorum calls and multicasts of -// the OnewayTest service. Its calls execute on the configuration given to -// [NewOnewayTestClient]. If that configuration is empty, every call returns -// [gorums.ErrEmptyConfig]. +// OnewayTestClient is the client API for OnewayTest quorum calls and +// multicasts on the client's configuration. If the configuration is empty, no +// message is sent and the call fails with [gorums.ErrEmptyConfig]. type OnewayTestClient interface { // Multicast starts a one-way call on the client's configuration; no reply // is returned. Use gorums.MapRequest to send a different message to each node. @@ -55,10 +54,9 @@ type onewayTestClient struct { config Config } -// OnewayTestNodeClient is the client API for the remote calls and unicasts -// of the OnewayTest service. Its calls execute on the node given to -// [NewOnewayTestNodeClient]. If that node is nil, every call returns -// [gorums.ErrNoNode]. +// OnewayTestNodeClient is the client API for OnewayTest remote calls and +// unicasts on the client's node. If the node is nil, no message is sent and the +// call fails with [gorums.ErrNoNode]. type OnewayTestNodeClient interface { // Unicast starts a one-way call on the client's node; no reply is // returned. @@ -96,7 +94,7 @@ func (c onewayTestClient) Multicast(ctx context.Context, in *Request) *gorums.On return gorumsimpl.Multicast(ctx, c.config, in, "oneway.OnewayTest.Multicast") } -// OnewayTestServer is the server-side API for the OnewayTest Service +// OnewayTestServer is the server API for OnewayTest. type OnewayTestServer interface { Unicast(gorums.ServerContext, *Request) Multicast(gorums.ServerContext, *Request) diff --git a/internal/tests/ordering/ordering_gorums.pb.go b/internal/tests/ordering/ordering_gorums.pb.go index 41ef6de53..d21467780 100644 --- a/internal/tests/ordering/ordering_gorums.pb.go +++ b/internal/tests/ordering/ordering_gorums.pb.go @@ -19,10 +19,9 @@ const ( _ = gorumsimpl.EnforceVersion(gorumsimpl.MaxVersion - 12) ) -// OrderingClient is the client API for the quorum calls and multicasts of -// the Ordering service. Its calls execute on the configuration given to -// [NewOrderingClient]. If that configuration is empty, every call returns -// [gorums.ErrEmptyConfig]. +// OrderingClient is the client API for Ordering quorum calls and +// multicasts on the client's configuration. If the configuration is empty, no +// message is sent and the call fails with [gorums.ErrEmptyConfig]. type OrderingClient interface { // QuorumCall executes a quorum call on the client's configuration. Use // terminal methods like Majority(), First(), or Threshold(n) to retrieve the @@ -44,10 +43,9 @@ type orderingClient struct { config Config } -// OrderingNodeClient is the client API for the remote calls and unicasts -// of the Ordering service. Its calls execute on the node given to -// [NewOrderingNodeClient]. If that node is nil, every call returns -// [gorums.ErrNoNode]. +// OrderingNodeClient is the client API for Ordering remote calls and +// unicasts on the client's node. If the node is nil, no message is sent and the +// call fails with [gorums.ErrNoNode]. type OrderingNodeClient interface { // UnaryRPC executes a remote call on the client's node and returns its // reply. @@ -77,7 +75,7 @@ func (c orderingNodeClient) UnaryRPC(ctx context.Context, in *Request) (*Respons return gorumsimpl.RemoteCall[*Request, *Response](ctx, c.node, in, "ordering.Ordering.UnaryRPC") } -// OrderingServer is the server-side API for the Ordering Service +// OrderingServer is the server API for Ordering. type OrderingServer interface { QuorumCall(gorums.ServerContext, *Request) (*Response, error) UnaryRPC(gorums.ServerContext, *Request) (*Response, error) diff --git a/internal/tests/tls/tls_gorums.pb.go b/internal/tests/tls/tls_gorums.pb.go index c38339fbb..f37483c68 100644 --- a/internal/tests/tls/tls_gorums.pb.go +++ b/internal/tests/tls/tls_gorums.pb.go @@ -19,10 +19,9 @@ const ( _ = gorumsimpl.EnforceVersion(gorumsimpl.MaxVersion - 12) ) -// TLSNodeClient is the client API for the remote calls and unicasts -// of the TLS service. Its calls execute on the node given to -// [NewTLSNodeClient]. If that node is nil, every call returns -// [gorums.ErrNoNode]. +// TLSNodeClient is the client API for TLS remote calls and +// unicasts on the client's node. If the node is nil, no message is sent and the +// call fails with [gorums.ErrNoNode]. type TLSNodeClient interface { // TestTLS executes a remote call on the client's node and returns its // reply. @@ -48,7 +47,7 @@ func (c tlsNodeClient) TestTLS(ctx context.Context, in *Request) (*Response, err return gorumsimpl.RemoteCall[*Request, *Response](ctx, c.node, in, "tls.TLS.TestTLS") } -// TLSServer is the server-side API for the TLS Service +// TLSServer is the server API for TLS. type TLSServer interface { TestTLS(gorums.ServerContext, *Request) (*Response, error) } diff --git a/internal/tests/unresponsive/unresponsive_gorums.pb.go b/internal/tests/unresponsive/unresponsive_gorums.pb.go index 8b718e3d8..b6897b18f 100644 --- a/internal/tests/unresponsive/unresponsive_gorums.pb.go +++ b/internal/tests/unresponsive/unresponsive_gorums.pb.go @@ -19,10 +19,9 @@ const ( _ = gorumsimpl.EnforceVersion(gorumsimpl.MaxVersion - 12) ) -// UnresponsiveNodeClient is the client API for the remote calls and unicasts -// of the Unresponsive service. Its calls execute on the node given to -// [NewUnresponsiveNodeClient]. If that node is nil, every call returns -// [gorums.ErrNoNode]. +// UnresponsiveNodeClient is the client API for Unresponsive remote calls and +// unicasts on the client's node. If the node is nil, no message is sent and the +// call fails with [gorums.ErrNoNode]. type UnresponsiveNodeClient interface { // TestUnresponsive executes a remote call on the client's node and returns its // reply. @@ -48,7 +47,7 @@ func (c unresponsiveNodeClient) TestUnresponsive(ctx context.Context, in *Empty) return gorumsimpl.RemoteCall[*Empty, *Empty](ctx, c.node, in, "unresponsive.Unresponsive.TestUnresponsive") } -// UnresponsiveServer is the server-side API for the Unresponsive Service +// UnresponsiveServer is the server API for Unresponsive. type UnresponsiveServer interface { TestUnresponsive(gorums.ServerContext, *Empty) (*Empty, error) } diff --git a/runtime/gorumsimpl/call.go b/runtime/gorumsimpl/call.go index 9b62dac7a..63caf3be9 100644 --- a/runtime/gorumsimpl/call.go +++ b/runtime/gorumsimpl/call.go @@ -11,23 +11,26 @@ import ( "google.golang.org/protobuf/proto" ) -// QuorumCall executes a quorum-call on the nodes in config and returns -// a handle for consuming the responses. It panics if config is empty. +// QuorumCall returns a quorum-call handle for the nodes in config. +// The call is dispatched when the handle is consumed. If config is empty, +// the handle sends nothing and reports [gorums.ErrEmptyConfig]. // It is used by generated code. func QuorumCall[Req, Resp proto.Message](ctx context.Context, config gorums.Config, req Req, method string) *gorums.Call[Req, Resp] { return impl.QuorumCall[Req, Resp](ctx, config, req, method) } -// QuorumCallStream executes a streaming quorum-call on the nodes in config and -// returns a handle for consuming the responses. It panics if config is empty. +// QuorumCallStream returns a streaming quorum-call handle for the nodes in +// config. The call is dispatched when the handle is consumed. If config is +// empty, the handle sends nothing and reports [gorums.ErrEmptyConfig]. // It is used by generated code. func QuorumCallStream[Req, Resp proto.Message](ctx context.Context, config gorums.Config, req Req, method string) *gorums.Call[Req, Resp] { return impl.QuorumCallStream[Req, Resp](ctx, config, req, method) } -// Multicast executes a one-way call on every node in config. No reply is -// returned. Send errors are reported by [gorums.OnewayCall.Send] or -// [gorums.OnewayAsync.Wait]. It panics if config is empty. +// Multicast returns a one-way call handle for every node in config. +// [gorums.OnewayCall.Send] or [gorums.OnewayCall.Async] dispatches the call; +// Send errors are reported by Send or [gorums.OnewayAsync.Wait]. If config is +// empty, the handle sends nothing and reports [gorums.ErrEmptyConfig]. // It is used by generated code. func Multicast[Req proto.Message](ctx context.Context, config gorums.Config, req Req, method string) *gorums.OnewayCall[Req] { return impl.Multicast(ctx, config, req, method)