Documentation

Overview

    Package protocol provides implementations of different Thrift protocols.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    This section is empty.

    Types

    type EnvelopeAgnosticProtocol

    type EnvelopeAgnosticProtocol interface {
    	Protocol
    
    	// DecodeRequest reads an enveloped or un-enveloped struct from the given
    	// ReaderAt.
    	// This allows a Thrift request handler to transparently accept requests
    	// regardless of whether the caller is configured to submit envelopes.
    	// The caller specifies the expected envelope type, one of OneWay or Unary,
    	// on which the decoder asserts if the envelope is present.
    	DecodeRequest(et wire.EnvelopeType, r io.ReaderAt) (wire.Value, Responder, error)
    }

      EnvelopeAgnosticProtocol defines a specific way for a Thrift value to be encoded or decoded, additionally being able to decode requests without prior knowledge of whether the request is enveloped.

      The Binary protocol in particular can be upcast to EnvelopeAgnosticProtocol.

      var EnvelopeAgnosticBinary EnvelopeAgnosticProtocol

        EnvelopeAgnosticBinary implements the Thrift Binary Protocol, using DecodeRequest for request bodies that may or may not have an envelope. This in turn produces a responder with an EncodeResponse method so a handler can reply in-kind.

        EnvelopeAgnosticBinary makes some practical assumptions about messages to be able to distinguish enveloped, versioned enveloped, and not-enveloped messages reliably:

        1.  No message will use an envelope version greater than 0x7fff.  This
        would flip the bit that makes versioned envelopes recognizable.  The only
        envelope version we recognize today is version 1.
        
        2.  No message with an unversioned envelope will have a message name
        (procedure name) longer than 0x00ffffffff (three bytes of length prefix).
        This would roll into the byte that distinguishes the type of the first
        field of an un-enveloped struct.  This would require a 16MB procedure name.
        

        The overlapping grammars are:

        1.  Enveloped (strict, with version)
        
            versionbits:4 methodname~4 seqid:4 struct
        
            versionbits := 0x80000000 | (version:2 << 16) | messagetype:2
        
        2.  Enveloped (non-strict, without version)
        
            methodname~4 messagetype:1 seqid:4 struct
        
        3.  Unenveloped
        
            struct := (typeid:1 fieldid:2 <value>)* typeid:1=0x00
        

        A message can be,

        1.  Enveloped (strict)
        
            The message must begin with 0x80 -- the first byte of the version number.
        
        2.  Enveloped (non-strict)
        
            The message begins with the length of the method name. As long as the
            method name is not 16 MB long, the first byte of this message is 0x00. If
            the message contains at least 9 other bytes, it is enveloped using the
            non-strict format.
        
                4  bytes  method name length (minimum = 0)
                n  bytes  method name
                1  byte   message type
                4  bytes  sequence ID
                1  byte   empty struct (0x00)
                --------
                >10 bytes
        
        3.  Unenveloped
        
            If the message begins with 0x00 but does not contain any more bytes, it's
            a bare, un-enveloped empty struct.
        
            If the message begins with any other byte, it's an unenveloped message or
            an invalid request.
        

        type EnvelopeV0Responder

        type EnvelopeV0Responder struct {
        	Name  string
        	SeqID int32
        }

          EnvelopeV0Responder responds to requests with a non-strict (unversioned) envelope.

          func (EnvelopeV0Responder) EncodeResponse

          func (r EnvelopeV0Responder) EncodeResponse(v wire.Value, t wire.EnvelopeType, w io.Writer) error

            EncodeResponse writes the response to the writer using a non-strict envelope.

            type EnvelopeV1Responder

            type EnvelopeV1Responder struct {
            	Name  string
            	SeqID int32
            }

              EnvelopeV1Responder responds to requests with a strict, version 1 envelope.

              func (EnvelopeV1Responder) EncodeResponse

              func (r EnvelopeV1Responder) EncodeResponse(v wire.Value, t wire.EnvelopeType, w io.Writer) error

                EncodeResponse writes the response to the writer using a strict, version 1 envelope.

                type Protocol

                type Protocol interface {
                	// Encode the given Value and write the result to the given Writer.
                	Encode(v wire.Value, w io.Writer) error
                
                	// EncodeEnveloped encodes the enveloped value and writes the result
                	// to the given Writer.
                	EncodeEnveloped(e wire.Envelope, w io.Writer) error
                
                	// Decode reads a Value of the given type from the given Reader.
                	Decode(r io.ReaderAt, t wire.Type) (wire.Value, error)
                
                	// DecodeEnveloped reads an enveloped value from the given Reader.
                	// Enveloped values are assumed to be TStructs.
                	DecodeEnveloped(r io.ReaderAt) (wire.Envelope, error)
                }

                  Protocol defines a specific way for a Thrift value to be encoded or decoded.

                  var Binary Protocol

                    Binary implements the Thrift Binary Protocol. Binary can be cast up to EnvelopeAgnosticProtocol to support DecodeRequest.

                    type Responder

                    type Responder interface {
                    	// EncodeResponse writes a response value to the writer, with the envelope
                    	// style of the corresponding request.
                    	// The EnvelopeType should be either wire.Reply or wire.Exception.
                    	EncodeResponse(v wire.Value, t wire.EnvelopeType, w io.Writer) error
                    }

                      Responder captures how to respond to a request, concerning whether and what kind of envelope to use, how to match the sequence identifier of the corresponding request.

                      var NoEnvelopeResponder Responder = &noEnvelopeResponder{}

                        NoEnvelopeResponder responds to a request without an envelope.

                        Directories

                        Path Synopsis
                        Package binary implements the Thrift Binary protocol.
                        Package binary implements the Thrift Binary protocol.