github.com/cloudwego/kitex@v0.9.0/pkg/streaming/streaming.go (about)

     1  /*
     2   * Copyright 2021 CloudWeGo Authors
     3   *
     4   * Licensed under the Apache License, Version 2.0 (the "License");
     5   * you may not use this file except in compliance with the License.
     6   * You may obtain a copy of the License at
     7   *
     8   *     http://www.apache.org/licenses/LICENSE-2.0
     9   *
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS,
    12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   * See the License for the specific language governing permissions and
    14   * limitations under the License.
    15   */
    16  
    17  // Package streaming interface
    18  package streaming
    19  
    20  import (
    21  	"context"
    22  	"io"
    23  
    24  	"github.com/cloudwego/kitex/pkg/remote/trans/nphttp2/metadata"
    25  )
    26  
    27  // Stream both client and server stream
    28  type Stream interface {
    29  	// SetHeader sets the header metadata. It may be called multiple times.
    30  	// When call multiple times, all the provided metadata will be merged.
    31  	// All the metadata will be sent out when one of the following happens:
    32  	//  - ServerStream.SendHeader() is called;
    33  	//  - The first response is sent out;
    34  	//  - An RPC status is sent out (error or success).
    35  	SetHeader(metadata.MD) error
    36  	// SendHeader sends the header metadata.
    37  	// The provided md and headers set by SetHeader() will be sent.
    38  	// It fails if called multiple times.
    39  	SendHeader(metadata.MD) error
    40  	// SetTrailer sets the trailer metadata which will be sent with the RPC status.
    41  	// When called more than once, all the provided metadata will be merged.
    42  	SetTrailer(metadata.MD)
    43  	// Header is used for client side stream to receive header from server.
    44  	Header() (metadata.MD, error)
    45  	// Trailer is used for client side stream to receive trailer from server.
    46  	Trailer() metadata.MD
    47  	// Context the stream context.Context
    48  	Context() context.Context
    49  	// RecvMsg recvive message from peer
    50  	// will block until an error or a message received
    51  	// not concurrent-safety
    52  	RecvMsg(m interface{}) error
    53  	// SendMsg send message to peer
    54  	// will block until an error or enough buffer to send
    55  	// not concurrent-safety
    56  	SendMsg(m interface{}) error
    57  	// not concurrent-safety with SendMsg
    58  	io.Closer
    59  }
    60  
    61  // WithDoFinish should be implemented when:
    62  // (1) you want to wrap a stream in client middleware, and
    63  // (2) you want to manually call streaming.FinishStream(stream, error) to record the end of stream
    64  // Note: the DoFinish should be reentrant, better with a sync.Once.
    65  type WithDoFinish interface {
    66  	DoFinish(error)
    67  }
    68  
    69  // Args endpoint request
    70  type Args struct {
    71  	Stream Stream
    72  }
    73  
    74  // Result endpoint response
    75  type Result struct {
    76  	Stream Stream
    77  }