github.com/Jeffail/benthos/v3@v3.65.0/lib/input/reader/interface.go (about)

     1  package reader
     2  
     3  import (
     4  	"context"
     5  
     6  	"github.com/Jeffail/benthos/v3/lib/types"
     7  )
     8  
     9  // Type is a type that reads Benthos messages from an external source. If the
    10  // source supports acknowledgements then it is the responsibility of Type
    11  // implementations to ensure acknowledgements are not sent for consumed messages
    12  // until a subsequent Acknowledge call contains a nil error.
    13  type Type interface {
    14  	// Connect attempts to establish a connection to the source, if unsuccessful
    15  	// returns an error. If the attempt is successful (or not necessary) returns
    16  	// nil.
    17  	Connect() error
    18  
    19  	// Acknowledge, if applicable to the source, should send acknowledgments for
    20  	// (or commit) all unacknowledged (or uncommitted) messages that have thus
    21  	// far been consumed. If the error is non-nil this means the message was
    22  	// unsuccessfully propagated down the pipeline, in which case it is up to
    23  	// the implementation to decide whether to simply retry uncommitted messages
    24  	// that are buffered locally, or to send the error upstream.
    25  	Acknowledge(err error) error
    26  
    27  	// Read attempts to read a new message from the source.
    28  	Read() (types.Message, error)
    29  
    30  	types.Closable
    31  }
    32  
    33  // Sync is a type that reads Benthos messages from an external source. Messages
    34  // can be read continuously, but acknowledgements must be made synchronously
    35  // and apply for all read messages.
    36  type Sync interface {
    37  	// ConnectWithContext attempts to establish a connection to the source, if
    38  	// unsuccessful returns an error. If the attempt is successful (or not
    39  	// necessary) returns nil.
    40  	ConnectWithContext(ctx context.Context) error
    41  
    42  	// ReadNextWithContext attempts to read a new message from the source. If
    43  	// successful a message is returned. Messages returned remain unacknowledged
    44  	// until the next AcknowledgeWithContext call.
    45  	ReadNextWithContext(ctx context.Context) (types.Message, error)
    46  
    47  	// Acknowledge, if applicable to the source, should send acknowledgments for
    48  	// (or commit) all unacknowledged (or uncommitted) messages that have thus
    49  	// far been consumed. If the error is non-nil this means the message was
    50  	// unsuccessfully propagated down the pipeline, in which case it is up to
    51  	// the implementation to decide whether to simply retry uncommitted messages
    52  	// that are buffered locally, or to send the error upstream.
    53  	AcknowledgeWithContext(ctx context.Context, err error) error
    54  
    55  	types.Closable
    56  }
    57  
    58  // AsyncAckFn is a function used to acknowledge receipt of a message batch. The
    59  // provided response indicates whether the message batch was successfully
    60  // delivered. Returns an error if the acknowledge was not propagated.
    61  type AsyncAckFn func(context.Context, types.Response) error
    62  
    63  var noopAsyncAckFn AsyncAckFn = func(context.Context, types.Response) error {
    64  	return nil
    65  }
    66  
    67  // Async is a type that reads Benthos messages from an external source and
    68  // allows acknowledgements for a message batch to be propagated asynchronously.
    69  // If the source supports acknowledgements then it is the responsibility of Type
    70  // implementations to ensure acknowledgements are not sent for consumed messages
    71  // until a subsequent Acknowledge call contains a nil error.
    72  type Async interface {
    73  	// ConnectWithContext attempts to establish a connection to the source, if
    74  	// unsuccessful returns an error. If the attempt is successful (or not
    75  	// necessary) returns nil.
    76  	ConnectWithContext(ctx context.Context) error
    77  
    78  	// ReadWithContext attempts to read a new message from the source. If
    79  	// successful a message is returned along with a function used to
    80  	// acknowledge receipt of the returned message. It's safe to process the
    81  	// returned message and read the next message asynchronously.
    82  	ReadWithContext(ctx context.Context) (types.Message, AsyncAckFn, error)
    83  
    84  	types.Closable
    85  }