go.uber.org/yarpc@v1.72.1/api/transport/router.go (about)

     1  // Copyright (c) 2022 Uber Technologies, Inc.
     2  //
     3  // Permission is hereby granted, free of charge, to any person obtaining a copy
     4  // of this software and associated documentation files (the "Software"), to deal
     5  // in the Software without restriction, including without limitation the rights
     6  // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
     7  // copies of the Software, and to permit persons to whom the Software is
     8  // furnished to do so, subject to the following conditions:
     9  //
    10  // The above copyright notice and this permission notice shall be included in
    11  // all copies or substantial portions of the Software.
    12  //
    13  // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    14  // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    15  // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    16  // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    17  // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    18  // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    19  // THE SOFTWARE.
    20  
    21  package transport
    22  
    23  import (
    24  	"context"
    25  
    26  	"go.uber.org/zap/zapcore"
    27  )
    28  
    29  // TODO: Until golang/mock#4 is fixed, imports in the generated code have to
    30  // be fixed by hand. They use vendor/* import paths rather than direct.
    31  
    32  // Procedure specifies a single handler registered in the RouteTable.
    33  type Procedure struct {
    34  	// Name of the procedure.
    35  	Name string
    36  
    37  	// Service or empty to use the default service name.
    38  	Service string
    39  
    40  	// HandlerSpec specifying which handler and rpc type.
    41  	HandlerSpec HandlerSpec
    42  
    43  	// Encoding of the handler (optional) used for introspection and routing
    44  	// (if present).
    45  	Encoding Encoding
    46  
    47  	// Signature of the handler, for introspection. This should be a snippet of
    48  	// Go code representing the function definition.
    49  	Signature string
    50  }
    51  
    52  // MarshalLogObject implements zap.ObjectMarshaler.
    53  func (p Procedure) MarshalLogObject(enc zapcore.ObjectEncoder) error {
    54  	// Passing a Procedure as a zap.ObjectMarshaler allocates, so we shouldn't
    55  	// do it on the request path.
    56  	enc.AddString("name", p.Name)
    57  	enc.AddString("service", p.Service)
    58  	enc.AddString("encoding", string(p.Encoding))
    59  	enc.AddString("signature", p.Signature)
    60  	return enc.AddObject("handler", p.HandlerSpec)
    61  }
    62  
    63  // Less orders procedures lexicographically on (Service, Name, Encoding).
    64  func (p Procedure) Less(o Procedure) bool {
    65  	if p.Service != o.Service {
    66  		return p.Service < o.Service
    67  	}
    68  	if p.Name != o.Name {
    69  		return p.Name < o.Name
    70  	}
    71  	return p.Encoding < o.Encoding
    72  }
    73  
    74  // Router maintains and provides access to a collection of procedures
    75  type Router interface {
    76  	// Procedures returns a list of procedures that
    77  	// have been registered so far.
    78  	Procedures() []Procedure
    79  
    80  	// Choose decides a handler based on a context and transport request
    81  	// metadata, or returns an UnrecognizedProcedureError if no handler exists
    82  	// for the request.  This is the interface for use in inbound transports to
    83  	// select a handler for a request.
    84  	Choose(ctx context.Context, req *Request) (HandlerSpec, error)
    85  }
    86  
    87  // RouteTable is an mutable interface for a Router that allows Registering new
    88  // Procedures
    89  type RouteTable interface {
    90  	Router
    91  
    92  	// Registers zero or more procedures with the route table.
    93  	Register([]Procedure)
    94  }