README
¶
PubSub Tools
pubsubtools is a utils package that contains helper functions that contains Google messaging (Publisher, Subscriber) utilities.
Installing it
pubsubtools is compatible with modern Go releases in module mode, with Go installed:
go get -u github.com/savannahghi/pubsubtools
will resolve and add the package to the current development module, along with its dependencies.
Alternatively the same can be achieved if you use import in a package:
import "github.com/savannahghi/pubsubtools"
and run go get without parameters.
The package name is pubsubtools
Developing
The default branch library is main
We try to follow semantic versioning ( https://semver.org/ ). For that reason, every major, minor and point release should be tagged.
git tag -m "v0.0.1" "v0.0.1"
git push --tags
Continuous integration tests must pass on Travis CI. Our coverage threshold is 90% i.e you must keep coverage above 90%.
Environment variables
In order to run tests, you need to have an env.sh file similar to this one:
# Application settings
export DEBUG=true
export IS_RUNNING_TESTS=true
export SENTRY_DSN=<a Sentry Data Source Name>
export PORT=8080 # local only, set by the runtime in the cloud
# Google Cloud credentials
export GOOGLE_APPLICATION_CREDENTIALS="<path to a service account JSON file"
export GOOGLE_CLOUD_PROJECT="Google Cloud project id"
export FIREBASE_WEB_API_KEY="<a web API key that corresponds to the project named above>"
# Link shortening
export FIREBASE_DYNAMIC_LINKS_DOMAIN=https://bwlci.page.link
This file must not be committed to version control.
It is important to export the environment variables. If they are not exported,
they will not be visible to child processes e.g go test ./....
These environment variables should also be set up on Travis CI environment variable section.
Contributing
I would like to cover the entire GitHub API and contributions are of course always welcome. The
calling pattern is pretty well established, so adding new methods is relatively
straightforward. See CONTRIBUTING.md for details.
Versioning
In general, pubsubtools follows semver as closely as we can for tagging releases of the package. For self-contained libraries, the application of semantic versioning is relatively straightforward and generally understood. We've adopted the following versioning policy:
- We increment the major version with any incompatible change to non-preview functionality, including changes to the exported Go API surface or behavior of the API.
- We increment the minor version with any backwards-compatible changes to functionality, as well as any changes to preview functionality in the GitHub API. GitHub makes no guarantee about the stability of preview functionality, so neither do we consider it a stable part of the go-github API.
- We increment the patch version with any backwards-compatible bug fixes.
License
This library is distributed under the MIT license found in the LICENSE file.
Documentation
¶
Index ¶
- Constants
- Variables
- func EnsureSubscriptionsExist(ctx context.Context, pubsubClient *pubsub.Client, ...) error
- func EnsureTopicsExist(ctx context.Context, pubsubClient *pubsub.Client, topicIDs []string) error
- func GetPubSubTopic(m *PubSubPayload) (string, error)
- func GetPushSubscriptionConfig(ctx context.Context, pubsubClient *pubsub.Client, topicID string, ...) (*pubsub.SubscriptionConfig, error)
- func GetServiceAccountEmail() (string, error)
- func NamespacePubsubIdentifier(serviceName string, topicID string, environment string, version string) string
- func PublishToPubsub(ctx context.Context, pubsubClient *pubsub.Client, topicID string, ...) error
- func ReverseSubscriptionIDs(topicIDs []string, environment string, serviceName string, version string) map[string]string
- func SubscriptionIDs(topicIDs []string) map[string]string
- type PubSubMessage
- type PubSubPayload
Constants ¶
const ( // GoogleProjectNumberEnvVarName is a numeric project number that GoogleProjectNumberEnvVarName = "GOOGLE_PROJECT_NUMBER" // GoogleCloudProjectIDEnvVarName is used to determine the ID of the GCP project e.g for setting up StackDriver client GoogleCloudProjectIDEnvVarName = "GOOGLE_CLOUD_PROJECT" )
#nosec
const ( PubSubHandlerPath = "/pubsub" // TODO: make this Env Vars Aud = "bewell.co.ke" )
pubsub constants
Variables ¶
var (
// TimeLocation default timezone
TimeLocation, _ = time.LoadLocation("Africa/Nairobi")
)
Functions ¶
func EnsureSubscriptionsExist ¶
func EnsureSubscriptionsExist( ctx context.Context, pubsubClient *pubsub.Client, topicSubscriptionMap map[string]string, callbackURL string, ) error
EnsureSubscriptionsExist ensures that the subscriptions named in the supplied topic:subscription map exist. If any does not exist, it is created.
func EnsureTopicsExist ¶
func EnsureTopicsExist( ctx context.Context, pubsubClient *pubsub.Client, topicIDs []string, ) error
EnsureTopicsExist creates the topic(s) in the suppplied list if they do not already exist.
func GetPubSubTopic ¶
func GetPubSubTopic(m *PubSubPayload) (string, error)
GetPubSubTopic retrieves a pubsub topic from a pubsub payload.
It follows a convention where the topic is sent as an attribute under the `topicID` key.
func GetPushSubscriptionConfig ¶
func GetPushSubscriptionConfig( ctx context.Context, pubsubClient *pubsub.Client, topicID string, callbackURL string, ) (*pubsub.SubscriptionConfig, error)
GetPushSubscriptionConfig creates a push subscription configuration with the supplied parameters.
func GetServiceAccountEmail ¶
GetServiceAccountEmail inspects the environment to get the project number and uses that to compose an email to use as a Google Cloud pub-sub email
func NamespacePubsubIdentifier ¶
func NamespacePubsubIdentifier( serviceName string, topicID string, environment string, version string, ) string
NamespacePubsubIdentifier uses the service name, environment and version to create a "namespaced" pubsub identifier. This could be a topicID or subscriptionID.
func PublishToPubsub ¶
func PublishToPubsub( ctx context.Context, pubsubClient *pubsub.Client, topicID string, environment string, serviceName string, version string, payload []byte, ) error
PublishToPubsub sends the supplied payload to the indicated topic
func ReverseSubscriptionIDs ¶
func ReverseSubscriptionIDs( topicIDs []string, environment string, serviceName string, version string, ) map[string]string
ReverseSubscriptionIDs returns a (reversed) map of subscription IDs to topicIDs
func SubscriptionIDs ¶
SubscriptionIDs returns a map of topic IDs to subscription IDs
Types ¶
type PubSubMessage ¶
type PubSubMessage struct {
MessageID string `json:"messageId"`
Data []byte `json:"data"`
Attributes map[string]string `json:"attributes"`
}
PubSubMessage is a pub-sub message payload.
See https://cloud.google.com/pubsub/docs/push for more context.
The message that is POSTed looks like the example below:
{
"message": {
"attributes": {
"key": "value"
},
"data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGVyZSBpcyBteSBtZXNzYWdlIQ==",
"messageId": "136969346945"
},
"subscription": "projects/myproject/subscriptions/mysubscription"
}
type PubSubPayload ¶
type PubSubPayload struct {
Message PubSubMessage `json:"message"`
Subscription string `json:"subscription"`
}
PubSubPayload is the payload of a Pub/Sub event.
func VerifyPubSubJWTAndDecodePayload ¶
func VerifyPubSubJWTAndDecodePayload( w http.ResponseWriter, r *http.Request, ) (*PubSubPayload, error)
VerifyPubSubJWTAndDecodePayload confirms that there is a valid Google signed JWT and decodes the pubsub message payload into a struct.
It's use will simplify & shorten the handler funcs that process Cloud Pubsub push notifications.
Source Files