From 10f2e4cd5d6eb1bd383fdf3cf2e6190833fa9923 Mon Sep 17 00:00:00 2001 From: Tiago Peczenyj Date: Tue, 28 Mar 2023 09:32:48 +0200 Subject: [PATCH] update docs after `make all` --- auth/doc.go | 2 +- doc.go | 6 +++--- logging/logrus/options_test.go | 1 - logging/zap/doc.go | 2 -- ratelimit/doc.go | 2 +- recovery/doc.go | 2 +- retry/doc.go | 4 ++-- tags/doc.go | 2 +- tags/fieldextractor.go | 6 +++--- tracing/opentracing/doc.go | 3 +-- tracing/opentracing/interceptors_test.go | 2 +- validator/doc.go | 3 +-- 12 files changed, 15 insertions(+), 20 deletions(-) diff --git a/auth/doc.go b/auth/doc.go index 0550f023e..b8ae65b46 100644 --- a/auth/doc.go +++ b/auth/doc.go @@ -4,7 +4,7 @@ /* `grpc_auth` a generic server-side auth middleware for gRPC. -Server Side Auth Middleware +# Server Side Auth Middleware It allows for easy assertion of `:authorization` headers in gRPC calls, be it HTTP Basic auth, or OAuth2 Bearer tokens. diff --git a/doc.go b/doc.go index 718e10046..a80b57245 100644 --- a/doc.go +++ b/doc.go @@ -4,7 +4,7 @@ /* `grpc_middleware` is a collection of gRPC middleware packages: interceptors, helpers and tools. -Middleware +# Middleware gRPC is a fantastic RPC middleware, which sees a lot of adoption in the Golang world. However, the upstream gRPC codebase is relatively bare bones. @@ -13,7 +13,7 @@ This package, and most of its child packages provides commonly needed middleware client-side interceptors for retires, server-side interceptors for input validation and auth, functions for chaining said interceptors, metadata convenience methods and more. -Chaining +# Chaining By default, gRPC doesn't allow one to have more than one interceptor either on the client nor on the server side. `grpc_middleware` provides convenient chaining methods @@ -42,7 +42,7 @@ These interceptors will be executed from left to right: monitoring and then retr The retry interceptor will call every interceptor that follows it whenever when a retry happens. -Writing Your Own +# Writing Your Own Implementing your own interceptor is pretty trivial: there are interfaces for that. But the interesting bit exposing common data to handlers (and other middleware), similarly to HTTP Middleware design. diff --git a/logging/logrus/options_test.go b/logging/logrus/options_test.go index 0ab66ac3b..4fc8f1187 100644 --- a/logging/logrus/options_test.go +++ b/logging/logrus/options_test.go @@ -111,5 +111,4 @@ func TestDefaultMessageProducer(t *testing.T) { tc.verify(t, lastEntry) }) } - } diff --git a/logging/zap/doc.go b/logging/zap/doc.go index ffa6b5c31..8441c1f9e 100644 --- a/logging/zap/doc.go +++ b/logging/zap/doc.go @@ -17,7 +17,6 @@ the full request/response payload needs to be written with care, this can signif ZAP can also be made as a backend for gRPC library internals. For that use `ReplaceGrpcLoggerV2`. - *Server Interceptor* Below is a JSON formatted example of a log that would be logged by the server interceptor: @@ -68,7 +67,6 @@ Below is a JSON formatted example of a log that would be logged by the payload i Note - due to implementation ZAP differs from Logrus in the "grpc.request.content" object by having an inner "msg" object. - Please see examples and tests for examples of use. Please see settable_test.go for canonical integration through "zaptest" with golang testing infrastructure. */ diff --git a/ratelimit/doc.go b/ratelimit/doc.go index 2589a1d30..a5adb9dff 100644 --- a/ratelimit/doc.go +++ b/ratelimit/doc.go @@ -1,7 +1,7 @@ /* `ratelimit` a generic server-side ratelimit middleware for gRPC. -Server Side Ratelimit Middleware +# Server Side Ratelimit Middleware It allows to do grpc rate limit by your own rate limiter (e.g. token bucket, leaky bucket, etc.) diff --git a/recovery/doc.go b/recovery/doc.go index 2806de5e2..e324a2c54 100644 --- a/recovery/doc.go +++ b/recovery/doc.go @@ -4,7 +4,7 @@ /* `grpc_recovery` are interceptors that recover from gRPC handler panics. -Server Side Recovery Middleware +# Server Side Recovery Middleware By default a panic will be converted into a gRPC error with `code.Internal`. diff --git a/retry/doc.go b/retry/doc.go index f8ba7198a..da05ede56 100644 --- a/retry/doc.go +++ b/retry/doc.go @@ -4,7 +4,7 @@ /* `grpc_retry` provides client-side request retry logic for gRPC. -Client-Side Request Retry Interceptor +# Client-Side Request Retry Interceptor It allows for automatic retry, inside the generated gRPC code of requests based on the gRPC status of the reply. It supports unary (1:1), and server stream (1:n) requests. @@ -12,7 +12,7 @@ of the reply. It supports unary (1:1), and server stream (1:n) requests. By default the interceptors *are disabled*, preventing accidental use of retries. You can easily override the number of retries (setting them to more than 0) with a `grpc.ClientOption`, e.g.: - myclient.Ping(ctx, goodPing, grpc_retry.WithMax(5)) + myclient.Ping(ctx, goodPing, grpc_retry.WithMax(5)) Other default options are: retry on `ResourceExhausted` and `Unavailable` gRPC codes, use a 50ms linear backoff with 10% jitter. diff --git a/tags/doc.go b/tags/doc.go index 960638d0f..778bbdb80 100644 --- a/tags/doc.go +++ b/tags/doc.go @@ -1,7 +1,7 @@ /* `grpc_ctxtags` adds a Tag object to the context that can be used by other middleware to add context about a request. -Request Context Tags +# Request Context Tags Tags describe information about the request, and can be set and used by other middleware, or handlers. Tags are used for logging and tracing of requests. Tags are populated both upwards, *and* downwards in the interceptor-handler stack. diff --git a/tags/fieldextractor.go b/tags/fieldextractor.go index a4073ab49..e6c590737 100644 --- a/tags/fieldextractor.go +++ b/tags/fieldextractor.go @@ -35,9 +35,9 @@ func CodeGenRequestFieldExtractor(fullMethod string, req interface{}) map[string // TagBasedRequestFieldExtractor is a function that relies on Go struct tags to export log fields from requests. // These are usually coming from a protoc-plugin, such as Gogo protobuf. // -// message Metadata { -// repeated string tags = 1 [ (gogoproto.moretags) = "log_field:\"meta_tags\"" ]; -// } +// message Metadata { +// repeated string tags = 1 [ (gogoproto.moretags) = "log_field:\"meta_tags\"" ]; +// } // // The tagName is configurable using the tagName variable. Here it would be "log_field". func TagBasedRequestFieldExtractor(tagName string) RequestFieldExtractorFunc { diff --git a/tracing/opentracing/doc.go b/tracing/opentracing/doc.go index 7a58efc22..e30d3c5d0 100644 --- a/tracing/opentracing/doc.go +++ b/tracing/opentracing/doc.go @@ -4,7 +4,7 @@ /* `grpc_opentracing` adds OpenTracing -OpenTracing Interceptors +# OpenTracing Interceptors These are both client-side and server-side interceptors for OpenTracing. They are a provider-agnostic, with backends such as Zipkin, or Google Stackdriver Trace. @@ -17,6 +17,5 @@ All server-side spans are tagged with grpc_ctxtags information. For more information see: http://opentracing.io/documentation/ https://github.com/opentracing/specification/blob/master/semantic_conventions.md - */ package grpc_opentracing diff --git a/tracing/opentracing/interceptors_test.go b/tracing/opentracing/interceptors_test.go index 7dc7cfa3d..0c45dcecf 100644 --- a/tracing/opentracing/interceptors_test.go +++ b/tracing/opentracing/interceptors_test.go @@ -337,4 +337,4 @@ func (jaegerFormatExtractor) Extract(carrier interface{}) (mocktracer.MockSpanCo return rval, err } return rval, nil -} \ No newline at end of file +} diff --git a/validator/doc.go b/validator/doc.go index 7205520a2..0059801dd 100644 --- a/validator/doc.go +++ b/validator/doc.go @@ -4,7 +4,7 @@ /* `grpc_validator` is a generic request contents validator server-side middleware for gRPC. -Request Validator Middleware +# Request Validator Middleware Validating input is important, and hard. It also causes a lot of boilerplate code. This middleware checks for the existence of a `Validate` method on each of the messages of a gRPC request. This @@ -16,7 +16,6 @@ While it is generic, it was intended to be used with https://github.com/mwitkow/ a Go protocol buffers codegen plugin that creates the `Validate` methods (including nested messages) based on declarative options in the `.proto` files themselves. For example: - syntax = "proto3"; package validator.examples; import "github.com/mwitkow/go-proto-validators/validator.proto";