Add documentation about FetchPartitionMetadata rpc
@@ -41,6 +41,7 @@ A high-level client has the following operations:
| [PublishAsync](#publishasync) | Publishes a new message to a Liftbridge stream asynchronously |
| [PublishToSubject](#publishtosubject) | Publishes a new message to a NATS subject |
| [FetchMetadata](#fetchmetadata) | Retrieves metadata from the cluster |
+| [FetchPartitionMetadata](#fetchpartitionmetadata) | Retrives partition metadata from partition leader |
| [Close](#close) | Closes any client connections to Liftbridge |
Below is the interface definition of the Go Liftbridge client. We'll walk
@@ -121,6 +122,11 @@ type Client interface {
// FetchMetadata returns cluster metadata including broker and stream
// information.
FetchMetadata(ctx context.Context) (*Metadata, error)
+
+ // FetchPartitionMetadata retrieves the latest partition metadata from partition leader
+ // The main interest is to retrieve Highest Watermark and Newest Offset
+ FetchPartitionMetadata(ctx context.Context, stream string, partitionID int32) ( *PartitionMetadataResponse, error)
+
}
```
@@ -698,6 +704,29 @@ In the Go client example above, `FetchMetadata` takes one argument:
[Implementation Guidance](#fetchmetadata-implementation)
+### FetchPartitionMetadata
+```golang
+ // FetchPartitionMetadata retrieves the latest partition metadata from partition leader
+ // The main interest is to retrieve Highest Watermark and Newest Offset
+ FetchPartitionMetadata(ctx context.Context, stream string, partitionID int32) ( *PartitionMetadataResponse, error)
+```
+Liftbridge provides a partition metadata API which can be used to retrieve information of a partition.
+Most importantly, there are usecases where it is useful to retrieve highest watermark and newest offset of the partition for tighter control of the subscriptions. A few key points to take into account:
+
+- The client must connect to paritition leader to fetch partition information. It is important to keep in mind
+ that as the highest watermark and newest offset is concerned, only partition leader maintains the complete vision of those data. Thus, the request must be sent to the partition leader.
+
+- The client should maintain an internal version of the metadata to know, for a given partition of a stream, which broker is currently the leader. It should be noted that the partition leader is concerned, and it is different from the cluster's metadata leader.
+
+In the Go client example, `FetchPartitionMetadata` should take 3 arguments:
+
+| Argument | Type | Description | Required |
+|:----|:----|:----|:----|
+| context | context | A [context](https://golang.org/pkg/context/#Context) which is a Go idiom for passing things like a timeout, cancellation signal, and other values across API boundaries. For Liftbridge, this is primarily used for two things: request timeouts and cancellation. In other languages, this might be replaced by explicit arguments, optional named arguments, or other language-specific idioms. | language-dependent |
+|stream|string|Stream name| True|
+|partitionID|int32| ID of the partition| True|
+
+[Implementation Guidance](#fetchpartitionmetadata-implementation)
### Close
```go
@@ -1819,3 +1848,11 @@ func (c *client) Close() error {
return nil
}
```
+
+### FetchPartitionMetadata Implementation
+`FetchPartitionMetadata` should return an immutable object which exposes partition
+metadata.
+
+*NOTE*: *It is important to keep in mind that the `FetchPartitionMetadataRequest` should be sent only to partition leader. It is the job of the client to figure out which broker is currently the partition leader. `Metadata` can be used to figure out which broker is currently the leader of the requested partition*
+
+The object contains information of the partition, notably the `Highest Watermark` and `Newest Offset`, which is necessary in case the client wants a tighter control on the subscription/publication of messages.
\ No newline at end of file
