# README

pulsar-client-go

A Go client library for the Apache Pulsar project.

Alternatives

The Pulsar project contains a Go client library that is a wrapper for the Pulsar C++ client library.

In comparison, this library is 100% Go (no cgo required). Outside the Go standard library, it has a single dependency on the golang/protbuf library.

Status & Goals

Status

This client is a work-in-progress and as such does not support all Pulsar features. It supports Pulsar 2.0 along with 1.22.

The following is an incomplete list of features that are not yet implemented:

Batch frame support
Payload compression support
Partitioned topics support
Athenz authentication support
Encryption support

Goals

100% Go
Simplicity

Installation

go get -u github.com/Comcast/pulsar-client-go

Note: The package name is pulsar

Example

An example of a producer and consumer can be seen in the included cli application.

Contributions

Contributions are welcome. Please create an issue before beginning work on major contributions. Refer to the CONTRIBUTING.md doc for more information.

Local Development

Integration Tests

Integration tests are provided that connect to a Pulsar sever. They are best run against a local instance of Pulsar, since they expect the standalone properties to exist. See below for instructions on installing Pulsar locally.

Integration tests will be run when provided the pulsar flag with the address of the Pulsar server to connect to. Example:

go test -v -pulsar "localhost:6650"

Protobuf

The Makefile target api/PulsarApi.pb.go will generate the required .go files using the Pulsar source's .proto files.

Usage:

$ make api/PulsarApi.pb.go

Local Pulsar

Notes on installing Pulsar locally.

Prereqs:

For Java8 on OSX, use these instructions stackoverflow

Checkout source from github

git clone [email protected]:apache/incubator-pulsar.git

Switch to desired tag, eg v1.22.1-incubating
Install Maven
```
brew install maven
```
Compile (full instructions)
```
mvn install -DskipTests
```

Launch Pulsar from Pulsar directory:

./bin/pulsar standalone --wipe-data --advertised-address localhost

Local Pulsar + TLS

The Makefile has various targets to support certificate generation, Pulsar TLS configuration, and topic setup:

Generate certificates for use by brokers, admin tool, and applications:
```
make certificates
```
This will create broker, admin, and app private/public pairs in the certs directory.
Generate configuration files for running Pulsar standalone and pulsar-admin with TLS enabled using generated certificates:
```
make pulsar-tls-conf
```
This will generate pulsar-conf/standalone.tls.conf and pulsar-conf/client.tls.conf files that can be used as the configurations for the standalone server and pulsar-admin tools respectively. They'll use the certificates in the certs directory. The files should be placed in the appropriate locations for use with those tools (probably the conf directory within the Pulsar directory). It's recommended to use symbolic-links to easily switch between configurations.
Setup sample topic on standalone server with TLS enabled:
```
make standalone-tls-ns
```
This will create a sample/standalone/ns1 topic. The app certificate will have produce, consume rights on the topic.