trpc.group/trpc-go/trpc-go@v1.0.3/transport/README.md (about)

     1  English | [中文](README.zh_CN.md)
     2  
     3  ## Background
     4  
     5  tRPC frameworks support multiple network protocols, such as tcp, udp, etc. For the udp protocol, a udp packet corresponds to an RPC request or response. For streaming protocols such as tcp, the framework requires additional package splitting mechanism. In order to isolate the differences between different network protocols, tRPC-Go provides a transport abstraction.
     6  
     7  ## Principle
     8  
     9  In tRPC-Go:
    10  
    11  - The client transport is responsible for establishing a connection with the peer and providing advanced features such as multiplexed;
    12  - The server transport is responsible for listening on socket, accepting incoming connections, and processing requests arriving at the connection.
    13  
    14  For streaming RPC, tRPC-Go also provides a set of transport abstractions.
    15  
    16  Below we will introduce the design and implementation of these transports in turn.
    17  
    18  ## ClientTransport
    19  
    20  The interface definition of [ClientTransport](client_transport.go) is as follows:
    21  
    22  ```go
    23  type ClientTransport interface {
    24      RoundTrip(ctx context.Context, req interface{}, opts ...RoundTripOption) (rsp interface{}, err error)
    25  }
    26  ```
    27  
    28  The `RoundTrip` method implements the sending and receiving of requests. It supports multiple connection modes, such as connection pooling and multiplexing. It also supports high-performance network library tnet. These options can be set via [`RoundTripOptions`](client_roundtrip_options.go), for example:
    29  
    30  ```go
    31  rsp, err := transport.RoundTrip(ctx, req,
    32      transport.WithDialNetwork("tcp"),
    33      transport.WithDialAddress(":8888"),
    34      transport.WithMultiplexed(true))
    35  ```
    36  
    37  ## ServerTransport
    38  
    39  The interface of [ServerTransport](transport.go) is defined as follows:
    40  
    41  ```go
    42  type ServerTransport interface {
    43      ListenAndServe(ctx context.Context, opts ...ListenServeOption) error
    44  }
    45  ```
    46  
    47  Just like `RoundTripOptions` of client side, the server has [`ServerTransportOptions`](server_listenserve_options.go). It can be used to set asynchronous processing, idle timeout, tls certificate, etc.
    48  
    49  ```go
    50  st := transport.NewServerTransport(transport.WithServerAsync(true))
    51  ```
    52  
    53  ## ClientStreamTransport
    54  
    55  [ClientStreamTransport](transport_stream.go) is used to send/receive streaming requests. Because the stream is created by the client, it provides the `Init` method to initialize the stream, such as establishing a network connection with the peer.
    56  
    57  ```go
    58  type ClientStreamTransport interface {
    59      Send(ctx context.Context, req []byte, opts ...RoundTripOption) error
    60      Recv(ctx context.Context, opts ...RoundTripOption) ([]byte, error)
    61      Init(ctx context.Context, opts ...RoundTripOption) error
    62      Close(ctx context.Context)
    63  }
    64  ```
    65  
    66  The client stream transport uses the same `RoundTripOption` as the ordinary RPC transport, and its underlying connection also supports multiplexing, etc.
    67  
    68  ## ServerStreamTransport
    69  
    70  [ServerStreamTransport](transport_stream.go) is used for server-side processing of streaming requests. When the server receives the client's Init packet, it creates a new goroutine to run the user's business logic, and the original network packet receiving goroutine is responsible for dispatching the received packets to the new goroutine.
    71  
    72  ```go
    73  type ServerStreamTransport interface {
    74      ServerTransport
    75      Send(ctx context.Context, req []byte) error
    76      Close(ctx context.Context)
    77  }
    78  ```
    79  
    80  Note that ServerStreamTransport embeds `ServerTransport`, which is used to listen on the port and create the corresponding network goroutine. Therefore, the `ListenServeOption` of ordinary RPC is also applicable to the streaming server.
    81  
    82  ## Split Package
    83  
    84  tRPC packets are composed of frame header, packet header, and packet body. When the server receives the request or the client receives the response packet (streaming requests are also applicable), the original data stream needs to be divided into individual requests and then handed over to the corresponding processing logic. [`codec.FramerBuild`](/codec/framer_builder.go) and [`codec.Framer`](/codec/framer_builder.go) are used to split the data stream.
    85  
    86  On the client side, you can set the frame builder through [`WithClientFramerBuilder`](client_roundtrip_options.go). On the server side, you can set it through [`WithServerFramerBuilder`](server_listenserve_options.go).