Solace PubSub+ Messaging API for Go

This repository contains sample code to showcase how the Solace PubSub+ Go API could be used. You can find:

1. /patterns --> runnable code showcasing different message exchange patters with the PubSub+ Go API.
2. /howtos --> code snippets showcasing how to use different features of the API. All howtos are named how_to_*.go with some sampler files under sub-folders.

Environment Setup

1. Install the latest supported version of Go from https://go.dev/doc/install. Currently, the samples are run and tested against Go v1.17.
2. Install the Solace PubSub+ Messaging API for Go into the root of this directory. This is done by either:
   1. run go get solace.dev/go/messaging
   2. Downloading the API archive from the Solace Community
   3. Clone the source code into the root of this repo
3. Make sure you have CGO, gcc, and stdlib headers installed
   1. e.g. on Ubuntu systems you can execute apt install -y gcc libc6-dev

Run Patterns

1. [Skip if existing] Initialize the directory with Go modules go mod init SolaceSamples.com/PubSub+Go.
2. [For local development] Modify the go.mod file to replace solace.dev/go/messaging with the local version of ./pubsubplus-go-client by adding the following line in your go.mod file

   replace solace.dev/go/messaging vX.Y.Z => ./pubsubplus-go-client
   

   where X.Y.Z refer to the version of the API being used.
3. [For local development] Unzip the contents of the PubSub+ Go API tar folder into a pubsubplus-go-client folder in this directory.
4. Run the samples. There are two way to run the samples:
   1. go run: Navigate to the patterns directory and execute go run <name_of_sample>.go
   2. go build: Navigate to the patterns directory and execute go build -o <name_of_sample> <name_of_sample>.go. This will produce an executable that can be run via ./<name_of_sample>
5. Note on environment variables: you can pass the hostname, VPN name, username, and password as environment variables before running the samples as follows:

SOLACE_HOST=<host_name> SOLACE_VPN=<vpn_name> SOLACE_USERNAME=<username> SOLACE_PASSWORD=<password> go run <name_of_sample>.go

Howtos

This directory contains code that showcases different features of the API

Client Certificate Authentication (mTLS)

The secure_connection.go sample demonstrates mutual TLS authentication where both client and server authenticate each other using X.509 certificates.

Quick Setup Steps

1. Generate client certificate and key in one command:

   openssl req -x509 -newkey rsa:2048 -keyout private.key -out certificate.pem -days 365 -nodes && cat private.key certificate.pem > combined_cert_and_key.pem

   When prompted, fill in the certificate details (the Common Name will be used as the client username).

2. Place the combined certificate in the fixtures directory:

   cp combined_cert_and_key.pem howtos/fixtures/api-client.pem

3. Download your broker's CA certificate:

   • Solace Cloud: Download DigiCertGlobalRootG2.crt.pem from your broker's "Connect" tab
   • On-premise: Get the CA certificate from your broker administrator

   Place it in the howtos/fixtures directory for certificate validation.

Broker Configuration Requirements

4. Configure your Solace broker: Documentation for Client Certificate Authentication
   • Add your client certificate to the broker's trusted certificate list
   • Create a client username matching your certificate's Common Name (CN)
   • Enable client certificate authentication on your Message VPN

Usage

Run the secure connection sample with the mTLS configuration section uncommented to test client certificate authentication:

cd howtos
go run secure_connection.go

Supported Environments

• See the list of supported environments here: Solace Go API - Supported Environments
• Monitor the Solace Community for updates on supported environments.

Resources

• Solace Developer Portal is at solace.dev.
• Ask the Solace Community for further discussions and questions.
• Solace PubSub+ Messaging API for Go documentation