Add documentation and changelog, update the serviceName in the instro…

…spect method

CHANGELOG.md

@@ -6,6 +6,34 @@ v1.2.0-dev (unreleased)
 
 -   Added experimental `transports/x/cherami` for transporting RPCs through
     [Cherami](https://eng.uber.com/cherami/).
+-   Added ability to specify a ServiceName for outbounds on the
+    transport.Outbounds object.  This will allow defining outbounds with a
+    `key` that is different from the service name they will use for requests.
+    If no ServiceName is specified, the ServiceName will fallback to the
+    config.Outbounds map `key`.
+
+    Before:
+
+    ```go
+    config.Outbounds['service'] := transport.Outbounds{
+        Unary: httpTransport.NewSingleOutbound(...)
+    }
+    ...
+    cc := dispatcher.ClientConfig('service')
+    cc.Service() // returns 'service'
+    ```
+
+    After (optional):
+
+    ```go
+    config.Outbounds['service-key'] := transport.Outbounds{
+        ServiceName: 'service'
+        Unary: httpTransport.NewSingleOutbound(...)
+    }
+    ...
+    cc := dispatcher.ClientConfig('service-key')
+    cc.Service() // returns 'service'
+    ```
 
 
 v1.1.0 (2017-01-24)

api/transport/outbound.go

@@ -64,7 +64,14 @@ type OnewayOutbound interface {
 	CallOneway(ctx context.Context, request *Request) (Ack, error)
 }
 
-// Outbounds encapsulates outbound types for a service
+// Outbounds encapsulates the outbound specification for a service.
+//
+// This includes the service name that will be used for outbound requests
+// as well as the Outbound that will be used to transport the request.  The
+// outbound will be one of:
+//
+// - Unary (send request and wait for response)
+// - Oneway (send request and continue once downstream acknowledges request)
 type Outbounds struct {
 	ServiceName string
 	Unary       UnaryOutbound

dispatcher.go

@@ -110,7 +110,7 @@ func NewDispatcher(cfg Config) *Dispatcher {
 
 // convertOutbounds applys outbound middleware and creates validator outbounds
 func convertOutbounds(outbounds Outbounds, mw OutboundMiddleware) Outbounds {
-	convertedOutbounds := make(Outbounds, len(outbounds))
+	outboundSpecs := make(Outbounds, len(outbounds))
 
 	for outboundKey, outs := range outbounds {
 		if outs.Unary == nil && outs.Oneway == nil {
@@ -138,14 +138,14 @@ func convertOutbounds(outbounds Outbounds, mw OutboundMiddleware) Outbounds {
 			serviceName = outs.ServiceName
 		}
 
-		convertedOutbounds[outboundKey] = transport.Outbounds{
+		outboundSpecs[outboundKey] = transport.Outbounds{
 			ServiceName: serviceName,
 			Unary:       unaryOutbound,
 			Oneway:      onewayOutbound,
 		}
 	}
 
-	return convertedOutbounds
+	return outboundSpecs
 }
 
 // collectTransports iterates over all inbounds and outbounds and collects all
@@ -202,8 +202,8 @@ func (d *Dispatcher) Inbounds() Inbounds {
 }
 
 // ClientConfig provides the configuration needed to talk to the given
-// service. This configuration may be directly passed into encoding-specific
-// RPC clients.
+// service through an outboundKey. This configuration may be directly
+// passed into encoding-specific RPC clients.
 //
 // 	keyvalueClient := json.New(dispatcher.ClientConfig("keyvalue"))
 //
@@ -418,7 +418,7 @@ func (d *Dispatcher) introspect() dispatcherStatus {
 		inbounds = append(inbounds, status)
 	}
 	var outbounds []introspection.OutboundStatus
-	for destService, o := range d.outbounds {
+	for _, o := range d.outbounds {
 		var status introspection.OutboundStatus
 		if o.Unary != nil {
 			if o, ok := o.Unary.(introspection.IntrospectableOutbound); ok {
@@ -436,7 +436,7 @@ func (d *Dispatcher) introspect() dispatcherStatus {
 			}
 			status.Type = "oneway"
 		}
-		status.Service = destService
+		status.Service = o.ServiceName
 		outbounds = append(outbounds, status)
 	}
 	return dispatcherStatus{