Documentation
¶
Index ¶
- Constants
- func AnswerStatus(ctx context.Context, err error) error
- func Decode(err error, reasons Reasons, byCode map[codes.Code]error) error
- func DecodeAppError(err error) error
- func Dial(target, secret string) (*grpc.ClientConn, error)
- func Forward(err error) error
- func NewServer(logger *slog.Logger, secret string, opts ...grpc.ServerOption) *grpc.Server
- func ReasonOf(err error) (string, bool)
- func Received(err error) error
- func RecordError(ctx context.Context, err error)
- func Restored(restored, received error) error
- func StopGracefully(srv *grpc.Server, done <-chan struct{}, deadline time.Duration)
- func StreamClientAuth(secret string) grpc.StreamClientInterceptor
- func StreamClientRequestID(ctx context.Context, desc *grpc.StreamDesc, cc *grpc.ClientConn, method string, ...) (grpc.ClientStream, error)
- func StreamServerAuth(secret string) grpc.StreamServerInterceptor
- func StreamServerRequestID(srv any, stream grpc.ServerStream, _ *grpc.StreamServerInfo, ...) error
- func StreamServerResult(logger *slog.Logger) grpc.StreamServerInterceptor
- func UnaryClientAuth(secret string) grpc.UnaryClientInterceptor
- func UnaryClientRequestID(ctx context.Context, method string, req, reply any, cc *grpc.ClientConn, ...) error
- func UnaryServerAuth(secret string) grpc.UnaryServerInterceptor
- func UnaryServerRequestID(ctx context.Context, req any, _ *grpc.UnaryServerInfo, ...) (any, error)
- func UnaryServerResult(logger *slog.Logger) grpc.UnaryServerInterceptor
- func WithAdapterMessage(sentinel error, message string) error
- type Reason
- type Reasons
Constants ¶
const InternalTokenMetadataKey = "x-memoh-internal-token"
const MaxMessageBytes = 16 << 20
const MetadataAdapterMessage = "adapter_message"
MetadataAdapterMessage is the ErrorInfo metadata key for an adapter's own error text.
const MetadataFault = "fault"
MetadataFault is the ErrorInfo metadata key for the fault the server attributes the failure to. The client's diagnostics read it as the remote fault; a status without it, from a server that predates it, is attributed as a dependency failure.
const RequestIDMetadataKey = "x-request-id"
RequestIDMetadataKey carries the caller's request id, so that what the callee logs for a call reports the id of the work that made it.
Variables ¶
This section is empty.
Functions ¶
func AnswerStatus ¶ added in v0.22.0
AnswerStatus is the status an RPC server answers err with, chosen by errs.Answer under the call's ctx. A cancellation by the caller is Canceled. Anything else is the envelope of the public error: its code is the reason, the catalog detail is the message, and the metadata holds the args and the fault this process attributes err to. An error without a public error of its own is the envelope of the generic code for its fault.
func Decode ¶ added in v0.22.0
Decode is what an RPC client returns for err, received from a call. Every internal RPC client decodes with it, so that a received failure is restored by the same rules everywhere:
- The result is marked remote and keeps the received status on its chain, where diagnostics read the status and the fault the server wrote.
- A status is restored, in order, to the sentinel reasons registers for its ErrorInfo reason, to the catalog apperror of a reason that is a catalog code, or to the sentinel byCode holds for its code. A status none of them restores is returned under the remote marker. No step reads the status message.
- Canceled and DeadlineExceeded stay statuses. Whether the call ended because its caller did is answered by the caller's own context, not by the code: a server, a closing connection and the caller all end a call with Canceled.
A sentinel restored by code reads as the sentinel followed by the received message, which is the only description such a status has. An error without a status, such as the io.EOF a stream reports when it ends, was not received and is returned unchanged.
func DecodeAppError ¶ added in v0.21.0
DecodeAppError restores the apperror of a received envelope whose reason is a catalog code, with the catalog args from its metadata. The fault stays on the received status, where diagnostics read it. It returns nil otherwise.
func Forward ¶ added in v0.22.0
Forward marks a decoded catalog error as the answer to end-user input this process forwarded, so that a client fault the server reported stays a client fault here and the error is answered to the end user as it would be in one process. A client that relays a user's request decodes its results through Forward; any other error is returned unchanged, since a status outside the catalog refuses what this process sent, not what the user did.
func NewServer ¶
NewServer builds an internal RPC server. Every call, including one refused by authentication, gets one result line on logger.
func ReasonOf ¶ added in v0.21.0
ReasonOf returns the ErrorInfo reason of a received envelope, also when err is an error Restored returned.
func Received ¶ added in v0.21.0
Received returns the status an RPC client received, from an error Restored returned; any other error is returned unchanged.
func RecordError ¶ added in v0.21.0
RecordError hands err to the RPC result line. A handler calls it when it maps a failure to a status that no longer carries the cause, so that the record still attributes the original error. Outside an RPC it does nothing.
func Restored ¶ added in v0.21.0
Restored is what an RPC client returns for a failure it restored from the received status. It reads as the restored error. Its chain holds the restored error and the received status under one remote marker, so errors.Is and errors.As find the restored value and diagnostics read the status: the error field of a result record renders the chain, received status included.
func StopGracefully ¶
StopGracefully drains srv but falls back to a hard stop when the context expires or the drain deadline passes — a long-lived Run stream with an active turn would otherwise block shutdown until fx kills the process.
func StreamClientAuth ¶
func StreamClientAuth(secret string) grpc.StreamClientInterceptor
func StreamClientRequestID ¶ added in v0.21.0
func StreamClientRequestID(ctx context.Context, desc *grpc.StreamDesc, cc *grpc.ClientConn, method string, streamer grpc.Streamer, opts ...grpc.CallOption) (grpc.ClientStream, error)
func StreamServerAuth ¶
func StreamServerAuth(secret string) grpc.StreamServerInterceptor
func StreamServerRequestID ¶ added in v0.21.0
func StreamServerRequestID(srv any, stream grpc.ServerStream, _ *grpc.StreamServerInfo, handler grpc.StreamHandler) error
func StreamServerResult ¶ added in v0.21.0
func StreamServerResult(logger *slog.Logger) grpc.StreamServerInterceptor
StreamServerResult is the streaming counterpart of UnaryServerResult. One stream is one unit of work and gets one result line.
func UnaryClientAuth ¶
func UnaryClientAuth(secret string) grpc.UnaryClientInterceptor
func UnaryClientRequestID ¶ added in v0.21.0
func UnaryClientRequestID(ctx context.Context, method string, req, reply any, cc *grpc.ClientConn, invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error
func UnaryServerAuth ¶
func UnaryServerAuth(secret string) grpc.UnaryServerInterceptor
func UnaryServerRequestID ¶ added in v0.21.0
func UnaryServerRequestID(ctx context.Context, req any, _ *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error)
UnaryServerRequestID puts the caller's request id into the call context. It runs before the result interceptor so the result line reports it.
func UnaryServerResult ¶ added in v0.21.0
func UnaryServerResult(logger *slog.Logger) grpc.UnaryServerInterceptor
UnaryServerResult writes the one result line of each unary call and returns the status with the fault that line attributes, as attributed describes. A handler panic is recorded and then propagated unchanged.
func WithAdapterMessage ¶ added in v0.21.0
WithAdapterMessage returns an error that reads as message and matches sentinel under errors.Is. An empty message returns sentinel.
Types ¶
type Reason ¶ added in v0.21.0
type Reason struct {
// Err is the sentinel. A client restores it so that errors.Is holds.
Err error
// Reason is the ErrorInfo reason. It is stable across releases.
Reason string
// Code is the status code.
Code codes.Code
// Message is the fixed English status message.
Message string
}
Reason registers one sentinel of an RPC package on the wire.
type Reasons ¶ added in v0.21.0
type Reasons []Reason
Reasons is the sentinel table of one RPC package.
Source Files
Directories