github.com/segmentio/kafka-go@v0.4.48-0.20240318174348-3f6244eb34fd/kafka.go (about)

     1  package kafka
     2  
     3  import "github.com/segmentio/kafka-go/protocol"
     4  
     5  // Broker represents a kafka broker in a kafka cluster.
     6  type Broker struct {
     7  	Host string
     8  	Port int
     9  	ID   int
    10  	Rack string
    11  }
    12  
    13  // Topic represents a topic in a kafka cluster.
    14  type Topic struct {
    15  	// Name of the topic.
    16  	Name string
    17  
    18  	// True if the topic is internal.
    19  	Internal bool
    20  
    21  	// The list of partition currently available on this topic.
    22  	Partitions []Partition
    23  
    24  	// An error that may have occurred while attempting to read the topic
    25  	// metadata.
    26  	//
    27  	// The error contains both the kafka error code, and an error message
    28  	// returned by the kafka broker. Programs may use the standard errors.Is
    29  	// function to test the error against kafka error codes.
    30  	Error error
    31  }
    32  
    33  // Partition carries the metadata associated with a kafka partition.
    34  type Partition struct {
    35  	// Name of the topic that the partition belongs to, and its index in the
    36  	// topic.
    37  	Topic string
    38  	ID    int
    39  
    40  	// Leader, replicas, and ISR for the partition.
    41  	//
    42  	// When no physical host is known to be running a broker, the Host and Port
    43  	// fields will be set to the zero values. The logical broker ID is always
    44  	// set to the value known to the kafka cluster, even if the broker is not
    45  	// currently backed by a physical host.
    46  	Leader   Broker
    47  	Replicas []Broker
    48  	Isr      []Broker
    49  
    50  	// Available only with metadata API level >= 6:
    51  	OfflineReplicas []Broker
    52  
    53  	// An error that may have occurred while attempting to read the partition
    54  	// metadata.
    55  	//
    56  	// The error contains both the kafka error code, and an error message
    57  	// returned by the kafka broker. Programs may use the standard errors.Is
    58  	// function to test the error against kafka error codes.
    59  	Error error
    60  }
    61  
    62  // Marshal encodes v into a binary representation of the value in the kafka data
    63  // format.
    64  //
    65  // If v is a, or contains struct types, the kafka struct fields are interpreted
    66  // and may contain one of these values:
    67  //
    68  //	nullable  valid on bytes and strings, encodes as a nullable value
    69  //	compact   valid on strings, encodes as a compact string
    70  //
    71  // The kafka struct tags should not contain min and max versions. If you need to
    72  // encode types based on specific versions of kafka APIs, use the Version type
    73  // instead.
    74  func Marshal(v interface{}) ([]byte, error) {
    75  	return protocol.Marshal(-1, v)
    76  }
    77  
    78  // Unmarshal decodes a binary representation from b into v.
    79  //
    80  // See Marshal for details.
    81  func Unmarshal(b []byte, v interface{}) error {
    82  	return protocol.Unmarshal(b, -1, v)
    83  }
    84  
    85  // Version represents a version number for kafka APIs.
    86  type Version int16
    87  
    88  // Marshal is like the top-level Marshal function, but will only encode struct
    89  // fields for which n falls within the min and max versions specified on the
    90  // struct tag.
    91  func (n Version) Marshal(v interface{}) ([]byte, error) {
    92  	return protocol.Marshal(int16(n), v)
    93  }
    94  
    95  // Unmarshal is like the top-level Unmarshal function, but will only decode
    96  // struct fields for which n falls within the min and max versions specified on
    97  // the struct tag.
    98  func (n Version) Unmarshal(b []byte, v interface{}) error {
    99  	return protocol.Unmarshal(b, int16(n), v)
   100  }