docs(pubsublite): more descriptive comments for the publish package
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
+// Package publish contains utilities related to publishing messages.
package publish
import (
@@ -19,9 +20,13 @@ import (
"strings"
)
-// Metadata holds the results of a published message.
+// Metadata holds the result of publishing a message to the Pub/Sub Lite
+// service.
type Metadata struct {
+ // The topic partition the message was published to.
Partition int
+
+ // The offset the message was assigned.
Offset int64
}
@@ -29,18 +34,28 @@ func (m *Metadata) String() string {
return fmt.Sprintf("%d:%d", m.Partition, m.Offset)
}
-// ParseMetadata converts a string obtained from Metadata.String()
-// back to Metadata.
-func ParseMetadata(input string) (*Metadata, error) {
- parts := strings.Split(input, ":")
+// ParseMetadata converts the ID string of a pubsub.PublishResult to Metadata.
+//
+// Example:
+// result := publisher.Publish(ctx, &pubsub.Message{Data: []byte("payload")})
+// id, err := result.Get(ctx)
+// if err != nil {
+// // TODO: Handle error.
+// }
+// metadata, err := publish.ParseMetadata(id)
+// if err != nil {
+// // TODO: Handle error.
+// }
+func ParseMetadata(id string) (*Metadata, error) {
+ parts := strings.Split(id, ":")
if len(parts) != 2 {
- return nil, fmt.Errorf("pubsublite: invalid encoded publish metadata %q", input)
+ return nil, fmt.Errorf("pubsublite: invalid encoded publish metadata %q", id)
}
partition, pErr := strconv.ParseInt(parts[0], 10, 64)
offset, oErr := strconv.ParseInt(parts[1], 10, 64)
if pErr != nil || oErr != nil {
- return nil, fmt.Errorf("pubsublite: invalid encoded publish metadata %q", input)
+ return nil, fmt.Errorf("pubsublite: invalid encoded publish metadata %q", id)
}
return &Metadata{Partition: int(partition), Offset: offset}, nil
}
