{"id":51045560,"url":"https://github.com/stackitcloud/pubsub-sdk-go","last_synced_at":"2026-06-22T13:32:20.635Z","repository":{"id":361128199,"uuid":"1216749458","full_name":"stackitcloud/pubsub-sdk-go","owner":"stackitcloud","description":"STACKIT PubSub SDK for Go","archived":false,"fork":false,"pushed_at":"2026-05-29T08:50:29.000Z","size":45,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-29T10:22:46.043Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stackitcloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-21T07:40:22.000Z","updated_at":"2026-05-29T08:49:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/stackitcloud/pubsub-sdk-go","commit_stats":null,"previous_names":["stackitcloud/pubsub-sdk-go"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/stackitcloud/pubsub-sdk-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackitcloud%2Fpubsub-sdk-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackitcloud%2Fpubsub-sdk-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackitcloud%2Fpubsub-sdk-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackitcloud%2Fpubsub-sdk-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stackitcloud","download_url":"https://codeload.github.com/stackitcloud/pubsub-sdk-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackitcloud%2Fpubsub-sdk-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34651748,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-22T13:32:19.953Z","updated_at":"2026-06-22T13:32:20.620Z","avatar_url":"https://github.com/stackitcloud.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# STACKIT PubSub Go SDK\n\nWelcome to the PubSub Dataplane SDK.\nIt provides a convenient way to interact with STACKIT PubSub topics and subscriptions for publishing and consuming messages.\nThis guide will walk you through setting up clients, authenticating your requests, and performing common operations like publishing and pulling messages.\n\n## Prerequisites\n\nBefore you begin, you will need the following:\n\n* Go `1.25` or later.\n* A STACKIT project.\n* A Service Account with the necessary permissions for PubSub.\n* The ID of the topic you want to publish to and/or the subscription you want to pull from.\n\n### 1. Installation\n\nTo use the SDK in your project, install it using `go get`:\n\n```bash\ngo get github.com/stackitcloud/pubsub-sdk-go\n```\n\n### 2. Usage\n\nTo interact with the PubSub Dataplane, you need to create and configure a `Publisher` or a `Subscriber`.\nYou will find an [example Folder](./example) in the root directory, with ready to copy examples for using the SDK even easier.\n\nThe recommended way to handle authentication is by using a `RoundTripper` from the core STACKIT Go SDK, which automatically manages service account tokens.\nFor initiating the Roundtripper you need a service Account, this you can get in the STACKIT Portal.\nTo authenticate against the STACKIT CLI please take a look at the [Documentation](https://github.com/stackitcloud/stackit-cli/blob/main/docs/stackit_auth_get-access-token.md).\n\n```go\nroundTripper, err := auth.DefaultAuth(\u0026config.Configuration{\n    ServiceAccountKeyPath: \"./service-account-key.json\",\n})\nif err != nil {\n    log.Fatalf(\"Error creating authentication token: %v\", err)\n}\n\npublisher := pubsub.NewPublisher(topicID,\n    pubsub.WithHTTPRoundTripper(roundTripper),\n)\n```\n\n### 3. Logging Configuration\n\nThe SDK supports structured logging to help you debug and monitor your application. You can inject a custom logger using either the Go standard library's `slog` or the `logr` interface.\n\nBy default, the SDK outputs standard operational infos and errors. Enable debug-level logging for more granular troubleshooting.\n\n**Using `slog`:**\n\n```go\nimport (\n    \"log/slog\"\n    \"os\"\n)\n\n// Configure an slog logger for debug output\nopts := \u0026slog.HandlerOptions{\n    Level: slog.LevelDebug,\n}\nslogLogger := slog.New(slog.NewJSONHandler(os.Stdout, opts))\n\n// Pass the slog.Logger to the publisher or subscriber\ntopicID := uuid.MustParse(\"00000000-0000-0000-0000-000000000000\")\npublisher := pubsub.NewPublisher(topicID,\n    pubsub.WithHTTPRoundTripper(roundTripper),\n    pubsub.WithLogger(slogLogger),\n)\n```\n\n\u003e **Hint:** If your application already utilizes `logr` (for instance, via a backend like `zap`), you can skip `slog` and pass your `logr.Logger` instance directly to the configuration by using `pubsub.WithLogrLogger(yourLogrInstance)`.\n\n### 4. Using Methods\n\nOnce you have configured your clients, you can send messages to a topic or consume them from a subscription.\nTo consume messages, you Pull them, process them, and `Ack` (acknowledge) them.\n\n```go\n// Publish\ntopicID := uuid.MustParse(\"00000000-0000-0000-0000-000000000000\")\npublisher := pubsub.NewPublisher(topicID, pubsub.WithHTTPRoundTripper(roundTripper))\n\nmessages := [][]byte{\n    []byte(\"Hello, PubSub!\"),\n}\nmessageIDs, err := publisher.Publish(ctx, messages)\n\n// Pull\nsubscriptionID := uuid.MustParse(\"00000000-0000-0000-0000-000000000000\")\nsubscriber := pubsub.NewSubscriber(topicID, subscriptionID, pubsub.WithHTTPRoundTripper(roundTripper))\n\npulledMessages, err := subscriber.Pull(ctx, pubsub.WithMaxMessages(10))\n\n// Acknowledge\nackIDs := pulledMessages.GetAckIDs()\nerr = subscriber.Ack(ctx, ackIDs)\n```\n\n### 5. Error Handling\n\nThe SDK returns specific error types to help you handle different failure scenarios:\n* `pubsub.APIError`: Represents an error returned by the PubSub API (e.g., 404 Not Found if a topic doesn't exist).\n* `pubsub.NetworkError`: Represents a client-side network issue (e.g., a timeout).\n\n```go\n// Example of detailed error handling\n_, err := publisher.Publish(ctx, messages)\nif err != nil {\n    var apiErr *pubsub.APIError\n    if errors.As(err, \u0026apiErr) {\n        log.Printf(\"API Error [%d]: %s (Code: %s)\\n\",\n            apiErr.StatusCode, apiErr.Msg, apiErr.Code)\n\n        if apiErr.IsNotFound() {\n            log.Println(\"Action required: The specified topic or subscription does not exist.\")\n        }\n        return\n    }\n\n    var netErr *pubsub.NetworkError\n    if errors.As(err, \u0026netErr) {\n        log.Printf(\"Network Error: %v\\n\", netErr.Unwrap())\n\n        if netErr.IsTransient() {\n            log.Println(\"This is a temporary issue. It is safe to trigger a retry.\")\n        }\n        return\n    }\n\n    log.Fatalf(\"An unexpected error occurred: %v\", err)\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackitcloud%2Fpubsub-sdk-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstackitcloud%2Fpubsub-sdk-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackitcloud%2Fpubsub-sdk-go/lists"}