README
¶
Google Cloud Platform Pub/Sub
A project for learning and teaching pub/sub using Go in the Google Cloud Platform using Google's Pubsub package
Purpose
TL;DR: If you are not a software developer, find another project.
There is no normal end user functionality provided. It's a project implemented using Go to build demonstration executables so the user can inspect the source code and run the executables to learn how to implement simple pub/sub functionality in Google Cloud Platform using Google's Pub/Sub package.
Building
$ go build -o gcppubsubdemo ./cmd/...
Pub/Sub Emulator
This project is meant to be used with the GCP Pub/Sub emulator. See these installation and execution instructions to get it installed and running.
In summary, install with
$ gcloud components install pubsub-emulator
$ gcloud components update
Execute with
$ gcloud beta emulators pubsub start --project=PUBSUB_PROJECT_ID
or
$ gcloud beta emulators pubsub start --host-port 127.0.0.1:9999
Executing
Quick Start for gcppubsubdemo
In another terminal, execute the publisher with
$ $(gcloud beta emulators pubsub env-init)
$ gcppubsubdemo publish
And in another terminal, execute the subscriber with
$ $(gcloud beta emulators pubsub env-init)
$ gcppubsubdemo subscribe
The default for both the publish and subscribe commands are to
publish and receive data continuously. Use Ctrl-C to stop execution
noting that in this case, the subscription ID and topics will remain
created in the pub/sub emulator. When using the --once option these
will be removed upon exit.
The --verbose option is particularly useful when learning how the
code flows. It enables DEBUG and TRACE level logging useful for
following the code logic.
Help
There are command line options for gcppubsubdemo. Use the --help
flag to find them.
Examples
$ gcppubsubdemo --help
$ gcppubsubdemo subscribe --help
$ gcppubsubdemo publish --help
API and Design
The design of gcppubsubcdemo consists of command-line user
interface code in cmd/ driven with Cobra.
This code in turn drives the gcppubsubdemo package (API) in
the project root. This is mainly to illustrate good architecture.
Because the core pub/sub functionality is implemented as an API
it can allow for re-use in other projects. However, I don't plan
on this package ever evolving past the 0.0.x version because
this repository is for learning and this pub/sub code should be
implemented natively by other developers. You have been warned
when I break the API.
Documentation
This project is documented with this README.md, scattered code
comments, and full GoDoc documentation as if it was a viable API.
This is done to show good practices.
Contributing
Contributions and bug fixes (and there are bugs because I also used this code to learn) are welcome. When contributing new functionality, try to keep the code straightforward because the purpose of this project is to help fellow developers learn. Try to use functions rather than methods. Keep dependency injection to a minimum, etc.
Some areas for consideration:
- Defect remedies (bug fixes)
- Pub/Sub API usage improvements
- Unit Tests (as long as the code remains readable by novice Gophers)
- Additional command line options to expose more pub/sub functionality
- Documentation corrections or additional information
Inspiration
I had to learn this pubsub package for my day job. For me, learning means writing and experimenting with code snippets. After I learned the minimal amount to get the job done, I spent my evenings pulling these code snippets together into self-contained meaningful project to help others. This project is the result.
Documentation
¶
Overview ¶
Package gcppubsubdemo is a tool for teaching and learning Google Cloud Platform's pub/sub API. This package is not meant to be used as an API but it is documented like one for instructional purposes.
Quick usage examples for the package are shown below. For more information, see the documentation for the individual items.
Publishing ¶
To use the API for publishing, call the GetPublisher function to obtain a Publisher function to call. Call the Publisher function giving the data to publish as the only parameter. To shut down the Publisher, call the Publisher function with nil as the parameter. Failing to do so will leave pub/sub code and network operations initialized.
if publish, err := GetPublisher("GCP Name", "Topic Name"); err != nil {
fmt.Fprintln(os.Stderr, err)
} else {
publish([]byte("Payload"))
publish(nil)
}
Subscribing ¶
Subscribe to a topic by callng the Subscribe function, giving it a callback to execute when data is received. The callback should return true when it no longer wants to retrieve messages and shut down the subscription.
if err := Subscribe("GCP Name", "Topic Name", "Subscription ID", func(data []byte) bool {
fmt.Println(string(data)
return true
}); err != nil {
fmt.Fprintln(os.Stderr, err)
}
Logging ¶
Basic logging is implemented using the standard log package. Logging is disabled by default. When enabled with a call to LogLevel(), log output goes to os.Stderr but can be redirected by using LogOutput().
writer, _ := os.Create("logfile.log")
LogOutput(writer)
LogLevel(DebugLogLevel)
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LogLevel ¶
func LogLevel(level LogType)
LogLevel sets the log level. The supported levels are error (1), debug (2), trace (3). A level of 0 disables all logging. A level of 3 or higher enables everything.
Example ¶
// Enable error and debug logging LogLevel(DebugLogLevel)
Output:
func LogOutput ¶
LogOutput sets the logging output to an io.Writer. This allows the API user to direct log output to a file, for example.
Example ¶
writer, _ := os.Create("logfile.log")
LogOutput(writer)
Output:
func Subscribe ¶
func Subscribe(gcpName, topicName, subscriptionID string, callback PubsubReceiveCallback) error
Subscribe subscribes and retrieves pub/sub messages from a given Google Cloud Project and topic then calls the callback so the caller can process each message. The callback should return true when it no longer wants to retrieve messages and shut down the subscription.
If an error is encountered during initialization for the subscription, it is returned.
Example ¶
Subscribe("GCP Name", "Topic Name", "Subscription ID", func(data []byte) bool {
fmt.Println("Received Data:", string(data))
return true
})
Output:
Types ¶
type LogType ¶
type LogType int
LogType represents the type of logging to perform. Current types are DisableLogLeve, ErrorLogLevel, DebugLogLevel, and TraceLogLevel.
type Publisher ¶
Publisher is a function that is returned to caller from GetPublisher() and is used to by the caller to publish data
func GetPublisher ¶
GetPublisher initializes a pub/sub client and topic returning a Publisher function to the caller. The caller can then call the Publisher function with the data to be published. The caller can shut down the Publisher by calling it with a nil parameter. Failing to do so will leave pub/sub code and network operations initialized.
If an error is encountered during initialization, it is returned and the caller should not attempt to use the Publisher function.
Example ¶
publish, _ := GetPublisher("GCP Name", "Topic Name")
publish([]byte("Payload"))
Output:
type PubsubReceiveCallback ¶
PubsubReceiveCallback is called with the data returned from the subscriber as a parameter. If the implemented callback returns true the subscription will be deleted and Subscribe() will return.
Example ¶
var callback PubsubReceiveCallback = func(data []byte) bool {
fmt.Println("Received Data:", string(data))
return true
}
callback([]byte("data"))
Output:
Source Files
Directories