http

Documentation

Overview

Package http implements a YARPC transport based on the HTTP/1.1 protocol. The HTTP transport provides first class support for Unary RPCs and experimental support for Oneway RPCs.

Usage

An HTTP Transport must be constructed to use this transport.

httpTransport := http.NewTransport()

To serve your YARPC application over HTTP, pass an HTTP inbound in your yarpc.Config.

myInbound := httpTransport.NewInbound(":8080")
dispatcher := yarpc.NewDispatcher(yarpc.Config{
	Name: "myservice",
	Inbounds: yarpc.Inbounds{myInbound},
})

To make requests to a YARPC application that supports HTTP, pass an HTTP outbound in your yarpc.Config.

myserviceOutbound := httpTransport.NewSingleOutbound("http://127.0.0.1:8080")
dispatcher := yarpc.NewDispatcher(yarpc.Config{
	Name: "myclient",
	Outbounds: yarpc.Outbounds{
		"myservice": {Unary: myserviceOutbound},
	},
})

Note that stopping an HTTP transport does NOT immediately terminate ongoing requests. Connections will remain open until all clients have disconnected.

Wire Representation

YARPC requests and responses are sent as plain HTTP requests and responses. YARPC metadata is sent inside reserved HTTP headers. Application headers for requests and responses are sent as HTTP headers with the header names prefixed with a pre-defined string. See Constants for more information on the names of these headers. The request and response bodies are sent as-is in the HTTP request or response body.

See Also

YARPC Properties: https://github.com/yarpc/yarpc/blob/master/properties.md

Index

• Constants
• type Inbound
  • func (i *Inbound) Addr() net.Addr
  • func (i *Inbound) Introspect() introspection.InboundStatus
  • func (i *Inbound) IsRunning() bool
  • func (i *Inbound) SetRouter(router transport.Router)
  • func (i *Inbound) Start() error
  • func (i *Inbound) Stop() error
  • func (i *Inbound) Tracer(tracer opentracing.Tracer) *Inbound
  • func (i *Inbound) Transports() []transport.Transport
• type InboundOption
  • func Mux(pattern string, mux *http.ServeMux) InboundOption
• type Outbound
  • func NewOutbound(chooser peer.Chooser, opts ...OutboundOption) *Outbound
  • func (o *Outbound) Call(ctx context.Context, treq *transport.Request) (*transport.Response, error)
  • func (o *Outbound) CallOneway(ctx context.Context, treq *transport.Request) (transport.Ack, error)
  • func (o *Outbound) Introspect() introspection.OutboundStatus
  • func (o *Outbound) IsRunning() bool
  • func (o *Outbound) Start() error
  • func (o *Outbound) Stop() error
  • func (o *Outbound) Transports() []transport.Transport
• type OutboundOption
  • func URLTemplate(template string) OutboundOption
• type Transport
  • func NewTransport(opts ...TransportOption) *Transport
  • func (a *Transport) IsRunning() bool
  • func (t *Transport) NewInbound(addr string, opts ...InboundOption) *Inbound
  • func (t *Transport) NewOutbound(chooser peer.Chooser, opts ...OutboundOption) *Outbound
  • func (t *Transport) NewSingleOutbound(uri string, opts ...OutboundOption) *Outbound
  • func (a *Transport) ReleasePeer(pid peer.Identifier, sub peer.Subscriber) error
  • func (a *Transport) RetainPeer(pid peer.Identifier, sub peer.Subscriber) (peer.Peer, error)
  • func (a *Transport) Start() error
  • func (a *Transport) Stop() error
• type TransportOption
  • func KeepAlive(t time.Duration) TransportOption
  • func Tracer(tracer opentracing.Tracer) TransportOption

Examples

• Inbound
• Mux
• Outbound

Constants

const (
	// Name of the service sending the request. This corresponds to the
	// Request.Caller attribute.
	CallerHeader = "Rpc-Caller"

	// Name of the encoding used for the request body. This corresponds to the
	// Request.Encoding attribute.
	EncodingHeader = "Rpc-Encoding"

	// Amount of time (in milliseconds) within which the request is expected
	// to finish.
	TTLMSHeader = "Context-TTL-MS"

	// Name of the procedure being called. This corresponds to the
	// Request.Procedure attribute.
	ProcedureHeader = "Rpc-Procedure"

	// Name of the service to which the request is being sent. This
	// corresponds to the Request.Service attribute.
	ServiceHeader = "Rpc-Service"

	// Shard key used by the destined service to shard the request. This
	// corresponds to the Request.ShardKey attribute.
	ShardKeyHeader = "Rpc-Shard-Key"

	// The traffic group responsible for handling the request. This
	// corresponds to the Request.RoutingKey attribute.
	RoutingKeyHeader = "Rpc-Routing-Key"

	// A service that can proxy the destined service. This corresponds to the
	// Request.RoutingDelegate attribute.
	RoutingDelegateHeader = "Rpc-Routing-Delegate"

	// Whether the response body contains an application error.
	ApplicationStatusHeader = "Rpc-Status"
)

HTTP headers used in requests and responses to send YARPC metadata.

const (
	// The request was successful.
	ApplicationSuccessStatus = "success"

	// An error occurred. The response body contains an application header.
	ApplicationErrorStatus = "error"
)

Valid values for the Rpc-Status header.

const ApplicationHeaderPrefix = "Rpc-Header-"

ApplicationHeaderPrefix is the prefix added to application header keys to send them in requests or responses.

Types

type Inbound

type Inbound struct {
	// contains filtered or unexported fields
}

Inbound receives YARPC requests using an HTTP server. It may be constructed using the NewInbound method on the Transport.

Example

package main

import (
	"log"

	"go.uber.org/yarpc"
	"go.uber.org/yarpc/transport/http"
)

func main() {
	transport := http.NewTransport()
	inbound := transport.NewInbound(":8888")

	dispatcher := yarpc.NewDispatcher(yarpc.Config{
		Name:     "myservice",
		Inbounds: yarpc.Inbounds{inbound},
	})
	if err := dispatcher.Start(); err != nil {
		log.Fatal(err)
	}
	defer dispatcher.Stop()
}

func (*Inbound) Addr

func (i *Inbound) Addr() net.Addr

Addr returns the address on which the server is listening. Returns nil if Start has not been called yet.

func (*Inbound) Introspect

func (i *Inbound) Introspect() introspection.InboundStatus

Introspect returns the state of the inbound for introspection purposes.

func (*Inbound) IsRunning

func (i *Inbound) IsRunning() bool

IsRunning returns whether the inbound is currently running

func (*Inbound) SetRouter

func (i *Inbound) SetRouter(router transport.Router)

SetRouter configures a router to handle incoming requests. This satisfies the transport.Inbound interface, and would be called by a dispatcher when it starts.

func (*Inbound) Start

func (i *Inbound) Start() error

Start starts the inbound with a given service detail, opening a listening socket.

func (*Inbound) Stop

func (i *Inbound) Stop() error

Stop the inbound, closing the listening socket.

func (*Inbound) Tracer

func (i *Inbound) Tracer(tracer opentracing.Tracer) *Inbound

Tracer configures a tracer on this inbound.

func (*Inbound) Transports

func (i *Inbound) Transports() []transport.Transport

Transports returns the inbound's HTTP transport.

type InboundOption

type InboundOption func(*Inbound)

InboundOption customizes the behavior of an HTTP Inbound constructed with NewInbound.

func Mux

func Mux(pattern string, mux *http.ServeMux) InboundOption

Mux specifies that the HTTP server should make the YARPC endpoint available under the given pattern on the given ServeMux. By default, the YARPC service is made available on all paths of the HTTP server. By specifying a ServeMux, users can narrow the endpoints under which the YARPC service is available and offer their own non-YARPC endpoints.

Example

package main

import (
	"fmt"
	"io"
	"log"

	nethttp "net/http"
	"os"

	"go.uber.org/yarpc"
	"go.uber.org/yarpc/transport/http"
)

func main() {
	// import nethttp "net/http"

	// We set up a ServeMux which provides a /health endpoint.
	mux := nethttp.NewServeMux()
	mux.HandleFunc("/health", func(w nethttp.ResponseWriter, _ *nethttp.Request) {
		if _, err := fmt.Fprintln(w, "hello from /health"); err != nil {
			panic(err)
		}
	})

	// This inbound will serve the YARPC service on the path /yarpc.  The
	// /health endpoint on the Mux will be left alone.
	transport := http.NewTransport()
	inbound := transport.NewInbound(":8888", http.Mux("/yarpc", mux))

	// Fire up a dispatcher with the new inbound.
	dispatcher := yarpc.NewDispatcher(yarpc.Config{
		Name:     "server",
		Inbounds: yarpc.Inbounds{inbound},
	})
	if err := dispatcher.Start(); err != nil {
		log.Fatal(err)
	}
	defer dispatcher.Stop()

	// Make a request to the /health endpoint.
	res, err := nethttp.Get("http://127.0.0.1:8888/health")
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()

	if _, err := io.Copy(os.Stdout, res.Body); err != nil {
		log.Fatal(err)
	}
}

Output:

hello from /health

type Outbound

type Outbound struct {
	// contains filtered or unexported fields
}

Outbound sends YARPC requests over HTTP. It may be constructed using the NewOutbound function or the NewOutbound or NewSingleOutbound methods on the HTTP Transport. It is recommended that services use a single HTTP transport to construct all HTTP outbounds, ensuring efficient sharing of resources across the different outbounds.

Example

package main

import (
	"go.uber.org/yarpc"
	"go.uber.org/yarpc/transport/http"
)

func main() {
	transport := http.NewTransport()

	yarpc.NewDispatcher(yarpc.Config{
		Name: "myservice",
		Outbounds: yarpc.Outbounds{
			"myservice": {
				Unary: transport.NewSingleOutbound("http://127.0.0.1:8888"),
			},
			"anotherservice": {
				Unary: transport.NewSingleOutbound("http://127.0.0.1:9999"),
			},
		},
	})
}

func NewOutbound

func NewOutbound(chooser peer.Chooser, opts ...OutboundOption) *Outbound

NewOutbound builds an HTTP outbound which sends requests to peers supplied by the given peer.Chooser. The URL template for used for the different peers may be customized using the URLTemplate option.

Peer Choosers used with the HTTP outbound MUST yield *hostport.Peer objects. Also note that the Chooser MUST have started before Outbound.Start is called.

func (*Outbound) Call

func (o *Outbound) Call(ctx context.Context, treq *transport.Request) (*transport.Response, error)

Call makes a HTTP request

func (*Outbound) CallOneway

func (o *Outbound) CallOneway(ctx context.Context, treq *transport.Request) (transport.Ack, error)

CallOneway makes a oneway request

func (*Outbound) Introspect

func (o *Outbound) Introspect() introspection.OutboundStatus

Introspect returns basic status about this outbound.

func (*Outbound) IsRunning

func (o *Outbound) IsRunning() bool

IsRunning returns whether the Outbound is running.

func (*Outbound) Start

func (o *Outbound) Start() error

Start the HTTP outbound

func (*Outbound) Stop

func (o *Outbound) Stop() error

Stop the HTTP outbound

func (*Outbound) Transports

func (o *Outbound) Transports() []transport.Transport

Transports returns the outbound's HTTP transport.

type OutboundOption

type OutboundOption func(*Outbound)

OutboundOption customizes an HTTP Outbound.

func URLTemplate

func URLTemplate(template string) OutboundOption

URLTemplate specifies the URL this outbound makes requests to. For peer.Chooser-based outbounds, the peer (host:port) spection of the URL may vary from call to call but the rest will remain unchanged. For single-peer outbounds, the URL will be used as-is.

type Transport

type Transport struct {
	// contains filtered or unexported fields
}

Transport keeps track of HTTP peers and the associated HTTP client. It allows using a single HTTP client to make requests to multiple YARPC services and pooling the resources needed therein.

func NewTransport

func NewTransport(opts ...TransportOption) *Transport

NewTransport creates a new HTTP transport for managing peers and sending requests

func (*Transport) IsRunning

func (a *Transport) IsRunning() bool

IsRunning returns whether the HTTP transport is running.

func (*Transport) NewInbound

func (t *Transport) NewInbound(addr string, opts ...InboundOption) *Inbound

NewInbound builds a new HTTP inbound that listens on the given address and sharing this transport.

func (*Transport) NewOutbound

func (t *Transport) NewOutbound(chooser peer.Chooser, opts ...OutboundOption) *Outbound

NewOutbound builds an HTTP outbound which sends requests to peers supplied by the given peer.Chooser. The URL template for used for the different peers may be customized using the URLTemplate option.

Peer Choosers used with the HTTP outbound MUST yield *hostport.Peer objects. Also note that the Chooser MUST have started before Outbound.Start is called.

func (*Transport) NewSingleOutbound

func (t *Transport) NewSingleOutbound(uri string, opts ...OutboundOption) *Outbound

NewSingleOutbound builds an outbound which sends YARPC requests over HTTP to the specified URL.

The URLTemplate option has no effect in this form.

func (*Transport) ReleasePeer

func (a *Transport) ReleasePeer(pid peer.Identifier, sub peer.Subscriber) error

ReleasePeer releases a peer from the peer.Subscriber and removes that peer from the Transport if nothing is listening to it

func (*Transport) RetainPeer

func (a *Transport) RetainPeer(pid peer.Identifier, sub peer.Subscriber) (peer.Peer, error)

RetainPeer gets or creates a Peer for the specified peer.Subscriber (usually a peer.Chooser)

func (*Transport) Start

func (a *Transport) Start() error

Start starts the HTTP transport.

func (*Transport) Stop

func (a *Transport) Stop() error

Stop stops the HTTP transport.

type TransportOption

type TransportOption func(*transportConfig)

TransportOption customizes the behavior of an HTTP transport.

func KeepAlive

func KeepAlive(t time.Duration) TransportOption

KeepAlive specifies the keep-alive period for the network connection. If zero, keep-alives are disabled.

Defaults to 30 seconds.

func Tracer

func Tracer(tracer opentracing.Tracer) TransportOption

Tracer configures a tracer for the transport and all its inbounds and outbounds.