add validator docs and regen auth readme

Author: Michal Witkowski

auth/README.md

@@ -1,4 +1,86 @@
-# gRPC Auth Interceptor
+# grpc_auth
+--
+    import "github.com/mwitkow/go-grpc-middleware/auth"
 
-Package `grpc_auther` provides an easy way to hook Bearer-token and TLS credentials authorization to your gRPC server.
+`grpc_auth` a generic server-side auth middleware for gRPC.
 
+
+### Server Side Auth Middleware
+
+It allows for easy assertion of `:authorization` headers in gRPC calls, be it
+HTTP Basic auth, or OAuth2 Bearer tokens.
+
+The middleware takes a user-customizable `AuthFunc`, which can be customized to
+verify and extract auth information from the request. The extracted information
+can be put in the `context.Context` of handlers downstream for retrieval.
+
+It also allows for per-service implementation overrides of `AuthFunc`. See
+`ServiceAuthFuncOverride`.
+
+Please see examples for simple examples of use.
+
+## Usage
+
+#### func  AuthFromMD
+
+```go
+func AuthFromMD(ctx context.Context, expectedScheme string) (string, error)
+```
+AuthFromMD is a helper function for extracting the :authorization header from
+the gRPC metadata of the request.
+
+It expects the `:authorization` header to be of a certain scheme (e.g. `basic`,
+`bearer`), in a case-insensitive format (see rfc2617, sec 1.2). If no such
+authorization is found, or the token is of wrong scheme, an error with gRPC
+status `Unauthenticated` is returned.
+
+#### func  StreamServerInterceptor
+
+```go
+func StreamServerInterceptor(authFunc AuthFunc) grpc.StreamServerInterceptor
+```
+StreamServerInterceptor returns a new unary server interceptors that performs
+per-request auth.
+
+#### func  UnaryServerInterceptor
+
+```go
+func UnaryServerInterceptor(authFunc AuthFunc) grpc.UnaryServerInterceptor
+```
+UnaryServerInterceptor returns a new unary server interceptors that performs
+per-request auth.
+
+#### type AuthFunc
+
+```go
+type AuthFunc func(ctx context.Context) (context.Context, error)
+```
+
+AuthFunc is the pluggable function that performs authentication.
+
+The passed in `Context` will contain the gRPC metadata.MD object (for
+header-based authentication) and the peer.Peer information that can contain
+transport-based credentials (e.g. `credentials.AuthInfo`).
+
+The returned context will be propagated to handlers, allowing user changes to
+`Context`. However, please make sure that the `Context` returned is a child
+`Context` of the one passed in.
+
+If error is returned, its `grpc.Code()` will be returned to the user as well as
+the verbatim message. Please make sure you use `codes.Unauthenticated` (lacking
+auth) and `codes.PermissionDenied` (authed, but lacking perms) appropriately.
+
+#### type ServiceAuthFuncOverride
+
+```go
+type ServiceAuthFuncOverride interface {
+	AuthFuncOverride(ctx context.Context, fullMethodName string) (context.Context, error)
+}
+```
+
+ServiceAuthFuncOverride allows a given gRPC service implementation to override
+the global `AuthFunc`.
+
+If a service implements the AuthFuncOverride method, it takes precedence over
+the `AuthFunc` method, and will be called instead of AuthFunc for all method
+invocations within that service.

auth/doc.go

@@ -2,7 +2,7 @@
 // See LICENSE for licensing terms.
 
 /*
-`grpc_auth` a generic provides server-side auth middleware for gRPC.
+`grpc_auth` a generic server-side auth middleware for gRPC.
 
 Server Side Auth Middleware
 

chain.go

@@ -11,6 +11,7 @@ import (
 )
 
 // ChainUnaryServer creates a single interceptor out of a chain of many interceptors.
+//
 // Execution is done in left-to-right order, including passing of context.
 // For example ChainUnaryServer(one, two, three) will execute one before two before three, and three
 // will see context changes of one and two.
@@ -30,6 +31,7 @@ func ChainUnaryServer(interceptors ...grpc.UnaryServerInterceptor) grpc.UnarySer
 }
 
 // ChainStreamServer creates a single interceptor out of a chain of many interceptors.
+//
 // Execution is done in left-to-right order, including passing of context.
 // For example ChainUnaryServer(one, two, three) will execute one before two before three.
 // If you want to pass context between interceptors, use WrapServerStream.
@@ -49,6 +51,7 @@ func ChainStreamServer(interceptors ...grpc.StreamServerInterceptor) grpc.Stream
 }
 
 // ChainUnaryClient creates a single interceptor out of a chain of many interceptors.
+//
 // Execution is done in left-to-right order, including passing of context.
 // For example ChainUnaryClient(one, two, three) will execute one before two before three.
 func ChainUnaryClient(interceptors ...grpc.UnaryClientInterceptor) grpc.UnaryClientInterceptor {
@@ -67,6 +70,7 @@ func ChainUnaryClient(interceptors ...grpc.UnaryClientInterceptor) grpc.UnaryCli
 }
 
 // ChainStreamClient creates a single interceptor out of a chain of many interceptors.
+//
 // Execution is done in left-to-right order, including passing of context.
 // For example ChainStreamClient(one, two, three) will execute one before two before three.
 func ChainStreamClient(interceptors ...grpc.StreamClientInterceptor) grpc.StreamClientInterceptor {
@@ -85,7 +89,7 @@ func ChainStreamClient(interceptors ...grpc.StreamClientInterceptor) grpc.Stream
 }
 
 // Chain creates a single interceptor out of a chain of many interceptors.
-
+//
 // WithUnaryServerChain is a grpc.Server config option that accepts multiple unary interceptors.
 // Basically syntactic sugar.
 func WithUnaryServerChain(interceptors ...grpc.UnaryServerInterceptor) grpc.ServerOption {

validator/README.md

@@ -1,7 +1,73 @@
-# gRPC Validation Interceptors
+# grpc_validator
+--
+    import "github.com/mwitkow/go-grpc-middleware/validator"
 
-Package `grpc_validator` provides an easy way to hook protobuf message validation as a gRPC
-interceptor across all your APIs.
+`grpc_validator` a generic request contents validator server-side middleware for
+gRPC.
 
-It primarily meant to be used with https://github.com/mwitkow/go-proto-validators, which code-gen
-assertions about allowed values from `.proto` files.
+
+### Request Validator Middleware
+
+Validating input is important, and hard. It also causes a lot of boiler plate.
+This middleware checks for the existance of a `Validate` method on each of the
+messages of a gRPC request. This includes the single request of the `Unary`
+calls, as well as each message of the inbound Stream calls. In case of a
+validation failure, a `InvalidArgument` gRPC status is returned, alongside with
+a description of the validation failure.
+
+While it is generic, it was indented to be used with
+https://github.com/mwitkow/go-proto-validators, 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";
+
+    message InnerMessage {
+      // some_integer can only be in range (1, 100).
+      int32 some_integer = 1 [(validator.field) = {int_gt: 0, int_lt: 100}];
+      // some_float can only be in range (0;1).
+      double some_float = 2 [(validator.field) = {float_gte: 0, float_lte: 1}];
+    }
+
+    message OuterMessage {
+      // important_string must be a lowercase alpha-numeric of 5 to 30 characters (RE2 syntax).
+      string important_string = 1 [(validator.field) = {regex: "^[a-z]{2,5}$"}];
+      // proto3 doesn't have `required`, the `msg_exist` enforces presence of InnerMessage.
+      InnerMessage inner = 2 [(validator.field) = {msg_exists : true}];
+    }
+
+The `OuterMessage.Validate` would include validation of regexes, existance of
+the InnerMessage and the range values within it. The `grpc_validator` middleware
+would then automatically use that to check all messages processed by the server.
+
+Please consult https://github.com/mwitkow/go-proto-validators for details of
+`protoc` invoation and other parameters of customization.
+
+## Usage
+
+#### func  StreamServerInterceptor
+
+```go
+func StreamServerInterceptor() grpc.StreamServerInterceptor
+```
+StreamServerInterceptor returns a new streaming server interceptors that
+validates incoming messages.
+
+The stage at which invalid messages will be rejected with `InvalidArgument`
+varies based on the type of the RPC. For `ServerStream` (1:m) requests, it will
+happen before reaching any userspace handlers. For `ClientStream` (n:1) or
+`BidiStream` (n:m) RPCs, the messages will be rejected on calls to
+`stream.Recv()`.
+
+#### func  UnaryServerInterceptor
+
+```go
+func UnaryServerInterceptor() grpc.UnaryServerInterceptor
+```
+UnaryServerInterceptor returns a new unary server interceptors that validates
+incoming messages.
+
+Invalid messages will be rejected with `InvalidArgument` before reaching any
+userspace handlers.

validator/doc.go

@@ -0,0 +1,45 @@
+// Copyright 2016 Michal Witkowski. All Rights Reserved.
+// See LICENSE for licensing terms.
+
+/*
+`grpc_validator` a generic request contents validator server-side middleware for gRPC.
+
+Request Validator Middleware
+
+Validating input is important, and hard. It also causes a lot of boiler plate. This middleware
+checks for the existance of a `Validate` method on each of the messages of a gRPC request. This
+includes the single request of the `Unary` calls, as well as each message of the inbound Stream calls.
+In case of a validation failure, a `InvalidArgument` gRPC status is returned, alongside with a
+description of the validation failure.
+
+While it is generic, it was indented to be used with https://github.com/mwitkow/go-proto-validators,
+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";
+
+	message InnerMessage {
+	  // some_integer can only be in range (1, 100).
+	  int32 some_integer = 1 [(validator.field) = {int_gt: 0, int_lt: 100}];
+	  // some_float can only be in range (0;1).
+	  double some_float = 2 [(validator.field) = {float_gte: 0, float_lte: 1}];
+	}
+
+	message OuterMessage {
+	  // important_string must be a lowercase alpha-numeric of 5 to 30 characters (RE2 syntax).
+	  string important_string = 1 [(validator.field) = {regex: "^[a-z]{2,5}$"}];
+	  // proto3 doesn't have `required`, the `msg_exist` enforces presence of InnerMessage.
+	  InnerMessage inner = 2 [(validator.field) = {msg_exists : true}];
+	}
+
+The `OuterMessage.Validate` would include validation of regexes, existance of the InnerMessage and
+the range values within it. The `grpc_validator` middleware would then automatically use that to
+check all messages processed by the server.
+
+Please consult https://github.com/mwitkow/go-proto-validators for details of `protoc` invoation and
+other parameters of customization.
+*/
+package grpc_validator

validator/validator.go

@@ -1,17 +1,6 @@
 // Copyright 2016 Michal Witkowski. All Rights Reserved.
 // See LICENSE for licensing terms.
 
-/*
-Package `grpc_validator` provides an easy way to hook protobuf message validation as a gRPC
-interceptor across all your APIs.
-
-It primarily meant to be used with https://github.com/mwitkow/go-proto-validators, which code-gen
-assertions about allowed values from `.proto` files.
-
-Basically this will invoke a .Validate() method on incoming message of the stream, if such method is
-defined. If that method returns an error, an `INVALID_ARGUMENT` gRPC status code is returned.
-*/
-
 package grpc_validator
 
 import (
@@ -25,6 +14,8 @@ type validator interface {
 }
 
 // UnaryServerInterceptor returns a new unary server interceptors that validates incoming messages.
+//
+// Invalid messages will be rejected with `InvalidArgument` before reaching any userspace handlers.
 func UnaryServerInterceptor() grpc.UnaryServerInterceptor {
 	return func(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
 		if v, ok := req.(validator); ok {
@@ -37,7 +28,11 @@ func UnaryServerInterceptor() grpc.UnaryServerInterceptor {
 }
 
 // StreamServerInterceptor returns a new streaming server interceptors that validates incoming messages.
-// The validation happens on message receives.
+//
+// The stage at which invalid messages will be rejected with `InvalidArgument` varies based on the
+// type of the RPC. For `ServerStream` (1:m) requests, it will happen before reaching any userspace
+// handlers. For `ClientStream` (n:1) or `BidiStream` (n:m) RPCs, the messages will be rejected on
+// calls to `stream.Recv()`.
 func StreamServerInterceptor() grpc.StreamServerInterceptor {
 	return func(srv interface{}, stream grpc.ServerStream, info *grpc.StreamServerInfo, handler grpc.StreamHandler) error {
 		wrapper := &recvWrapper{stream}