{"id":29572689,"url":"https://github.com/accelbyte/eventstream-go-sdk","last_synced_at":"2025-07-19T05:10:53.656Z","repository":{"id":34577078,"uuid":"178154914","full_name":"AccelByte/eventstream-go-sdk","owner":"AccelByte","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-22T03:10:06.000Z","size":399,"stargazers_count":1,"open_issues_count":4,"forks_count":17,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-22T04:21:10.870Z","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":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AccelByte.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-03-28T08:00:11.000Z","updated_at":"2025-05-22T03:07:50.000Z","dependencies_parsed_at":"2023-11-23T02:26:14.334Z","dependency_job_id":"db27880e-c0d7-415c-898f-031c53289e33","html_url":"https://github.com/AccelByte/eventstream-go-sdk","commit_stats":null,"previous_names":[],"tags_count":63,"template":false,"template_full_name":null,"purl":"pkg:github/AccelByte/eventstream-go-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Feventstream-go-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Feventstream-go-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Feventstream-go-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Feventstream-go-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AccelByte","download_url":"https://codeload.github.com/AccelByte/eventstream-go-sdk/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AccelByte%2Feventstream-go-sdk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265892512,"owners_count":23845034,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":"2025-07-19T05:10:53.034Z","updated_at":"2025-07-19T05:10:53.635Z","avatar_url":"https://github.com/AccelByte.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.com/AccelByte/eventstream-go-sdk.svg?branch=master)](https://travis-ci.com/AccelByte/eventstream-go-sdk)\n\n# eventstream-go-sdk\nGo SDK for integrating with AccelByte's event stream\n\n## Usage\n\n### Install\nThe eventstream-kafka-go is available in two major versions:\n#### v4\nThe eventstream-go-sdk v4 changed its underlying Kafka library from [segmentio/kafka-go](https://github.com/segmentio/kafka-go) \nto [confluentinc/confluent-kafka-go](https://github.com/confluentinc/confluent-kafka-go) which is a lightweight wrapper around \n[librdkafka](https://github.com/confluentinc/librdkafka), a finely tuned C client.\n\nEnabling CGO `CGO_ENABLED=1` is a must since the Go client is based on the C library librdkafka.\n\n```\ngo get -u github.com/AccelByte/eventstream-go-sdk/v4\n```\n\nWhen building your application in Alpine Linux (musl libc), you must pass `-tags musl` to go build.\n\n#### v3\n```\ngo get -u github.com/AccelByte/eventstream-go-sdk/v3\n```\n\n### Importing\n#### v4\n```go\neventstream \"github.com/AccelByte/eventstream-go-sdk/v4\"\n```\n\n#### v3\n```go\neventstream \"github.com/AccelByte/eventstream-go-sdk/v3\"\n```\n\nTo create a new event stream client, use this function:\n\n```go\nclient, err := eventstream.NewClient(prefix, stream, brokers, config)\n``` \n``NewClient`` requires 4 parameters :\n * prefix : Topic prefix from client (string)\n * stream : Stream name. e.g. kafka, stdout, none (string)\n * brokers : List of kafka broker (array of string)\n * config : Custom broker configuration from client. \n This is optional and only uses the first arguments. (variadic *BrokerConfig)   \n\n## Note for Maintainers\n\nPlease follow [semantic versioning](https://semver.org/) rule when releasing new version.\nNew version releases must be tagged based on their own corresponding major version:\n* If you make changes only in v3, you need to tag the new version as `3.x.x`\n* If you make changes only in v4, you need to tag the new version as `4.x.x`\n* If you make changes on both, you need to tag the new version as `3.x.x` and `4.x.x`\n\n## Supported Stream\nCurrently event stream are supported by these stream:\n\n### Kafka Stream\nPublish and subscribe an event to / from Kafka stream. \n\ncurrently compatible with golang version from 1.12+ and Kafka versions from 0.10.1.0 to 2.1.0.\n\nTo create a kafka stream client, just pass the stream parameter with `kafka`.\n\n#### Custom Configuration\nSDK support with custom configuration for kafka stream, that is :\n\n* DialTimeout : Timeout duration during connecting to kafka broker. Default: 10 Seconds (time.Duration)\n* ReadTimeout : Timeout duration during consume topic from kafka broker. Default: 10 Seconds (time.Duration)\n* WriteTimeout : Timeout duration during publish event to kafka broker. Default: 10 Seconds (time.Duration) \n* LogMode : eventstream will print log based on following levels: info, warn, debug, error and off. Default: off (string) \n* StrictValidation : If it set true, eventstream will enable strict validation for event fields, Default: False (boolean) \n\n```go\n    config := \u0026eventstream.BrokerConfig{\n\t\tLogMode:          eventstream.InfoLevel,\n\t\tStrictValidation: true,\n\t\tDialTimeout:      1 * time.Second,\n\t\tReadTimeout:      1 * time.Second,\n\t\tWriteTimeout:     1 * time.Second,\n\t}\n```\n\n#### Authentication\nSupported authentication mode for kafka stream:\n\n**1. SASL SCRAM**\n\nExample configuration:\n\n```go\n    config := \u0026eventstream.BrokerConfig{\n        ...\n        SecurityConfig: \u0026eventstream.SecurityConfig{\n            AuthenticationType: \"SASL-SCRAM\",\n            SASLUsername:       \"your-username\",\n            SASLPassword:       \"your-password\",\n        },\n    }\n```\n\n### Stdout Stream\nThis stream is for testing purpose. This will print the event in stdout. It should not be used in production since this \nwill print unnecessary log.\n\nTo create a stdout stream client, just pass the stream parameter with `stdout`.\n\n### Blackhole\nThis is used when client don't want the service to send event data to anywhere.\n\nTo create a blackhole client, just pass the stream parameter with `none`.\n\n## Publish Subscribe Event\n\n### Publish\nPublish or sent an event into stream. Client able to publish an event into a single topic.\nPublish to `kafka` stream support with exponential backoff retry. (max 3x)\n\nTo publish an event, use this function:\n```go\nerr := client.Publish(\n\t\tNewPublish().\n\t\t\tTopic(TopicName).\n\t\t\tEventName(EventName).\n\t\t\tNamespace(Namespace).\n\t\t\tKey(Key).\n\t\t\tClientID(ClientID).\n\t\t\tUserID(UserID).\n\t\t\tSessionID(SessionID).\n\t\t\tTraceID(TraceID).\n\t\t\tSpanContext(SpanContext).\n\t\t\tContext(Context).\n\t\t\tEventID(eventID int).\n\t\t\tEventType(eventType int).\n\t\t\tEventLevel(eventLevel int).\n\t\t\tServiceName(serviceName string).\n\t\t\tClientIDs(clientIDs []string).\n\t\t\tTargetUserIDs(targetUserIDs []string).\n\t\t\tTargetNamespace(targetNamespace string).\n\t\t\tPrivacy(privacy bool).\n\t\t\tAdditionalFields(additionalFields map[string]interface{}).\n\t\t\tVersion(Version).\n\t\t\tPayload(Payload).\n\t\t\tErrorCallback(func(event *Event, err error) {}))\n```\n\n#### Publish Parameters\n* Topic : Event topic. (string - alphaNumeric(256) - Required)\n* EventName : Event name. (string - alphaNumeric(256) - Required) \n* Namespace : Event namespace. (string - alphaNumeric(256) - Required)\n* ID : Kafka message ID. (string - default. random UUID v4 without Hyphens - optional)\n* key : Kafka message key. (string - default. random UUID v4 without Hyphens - optional)\n* ClientID : Publisher client ID. (string - UUID v4 without Hyphens)7\n* UserID : Publisher user ID. (string - UUID v4 without Hyphens)\n* SessionID : Publisher session ID. (string - UUID v4 without Hyphens)\n* TraceID : Trace ID. (string - UUID v4 without Hyphens)\n* SpanContext : Opentracing Jaeger Span Context(string - optional)\n* Context : Golang context. (context - default: context.background)\n* Version : Version of schema. (integer - default: `1`)\n* EventID : Event ID. Backward compatibility. (integer)\n* EventType : Event Type. Backward compatibility. (integer)\n* EventLevel : Event Level. Backward compatibility. (integer)\n* ServiceName : Service Name. Backward compatibility. (string)\n* ClientIDs : List of client IDs. Backward compatibility. ([]string - UUID v4 without Hyphens)\n* TargetUserIDs : List of target client IDs. Backward compatibility. ([]string - UUID v4 without Hyphens)\n* TargetNamespace : Target Namespace. Backward compatibility. (string)\n* SourceNamespace : Source Namespace. Backward compatibility. SourceNamespace tracks the trigger namespace, distinct from the event's occurrence namespace. (string  - optional)\n* Privacy : Privacy. Backward compatibility. (bool)\n* AdditionalFields : Additional fields. Backward compatibility. (map[string]interface{})\n* Payload : Additional attribute. (map[string]interface{})\n\n### Subscribe\nTo subscribe an event from specific topic in stream, client should be register a callback function that executed once event received.\nA callback aimed towards specific topic and event name.\n\nTo subscribe an event, use this function:\n```go\nerr := client.Register(\n\t\tNewSubscribe().\n\t\t\tTopic(topicName).\n\t\t\tEventName(mockEvent.EventName).\n\t\t\tGroupID(groupID).\n\t\t\tOffset(offset).\n\t\t\tContext(ctx).\n\t\t\tCallback(func(ctx context.Context, event *Event, err error) error { return nil }))\n```\n### Unsubscribe\nTo unsubscribe a topic from the stream, client should close passed context\n\nTo unsubscribe from the topic, use this function:\n```go\nctx, cancel := context.WithCancel(context.Background())\n\nerr := client.Register(\n    NewSubscribe().\n        Topic(topicName).\n        EventName(mockEvent.EventName).\n        GroupID(groupID).\n        Context(ctx).\n        Callback(func(ctx context.Context, event *Event, err error) error {\n            if ctx.Error() != nil {\n                // unsubscribed\n                return nil\n            }           \n\n            return nil\n        }))\n\ncancel() // cancel context to unsubscribe\n```\n\n#### Subscribe Parameters\n* Topic : Subscribed topic. (string - alphaNumeric(256) - Required)\n* Offset : Offset(position) inside the topic from which processing begins(int64 - Optional - default: `-1` (the tail))\n* GroupID : Message broker group ID. A random ID will be generated by the client if it's empty. (string - alphaNumeric(256) - default: generated ID)\n* GroupInstanceID : Message broker group instance ID for static group membership. Optional. (string - alphaNumeric(256) - default: empty)\n* EventName : Event name to subscribe. If it's empty, any event will trigger the callback. (string - alphaNumeric(256) - optional)\n* Callback : Callback function to be called when an event is received. (func(ctx context.Context,event *Event, err error) error {} - required)\n* CallbackRaw : Similar with Callback but a raw message will be passed instead. (func(ctx context.Context,msgValue []byte, err error) error {} - optional)\n* Context : Golang context. (context - default: context.background)\n* SendErrorDLQ : A flag to send error message of message processing to a DLQ topic which have following format: 'yourTopic-dlq' (string - alphaNumeric(256) - default: false)\n* AsyncCommitMessage : A flag to asynchronously commit message offset. This setting will be overridden by AutoCommitInterval on BrokerConfig.\n* Slug : Returns a string describing a unique subscriber (topic, eventName, groupID)\n\n\nCallback function passing 3 parameters:\n* ``ctx`` context to check that consumer unsubscribed \n* ``event`` is object that store event message. \n* ``err`` is an error that happen when consume the message.\n\nCallback function return 1 result(error):\n* return `nil` to commit the event(mark as processed)\n* return any error to retry processing(worker will be selected randomly)\n\n## Event Message\nEvent message is a set of event information that would be published or consumed by client.\n\nEvent message format :\n* id : Event ID (string - default. random UUID v4 without Hyphens)\n* name : Event name (string)\n* namespace : Event namespace (string)\n* traceId : Trace ID (string - UUID v4 without Hyphens)\n* spanContext : Opentracing Jaeger Span Context (string - optional)\n* clientId : Publisher client ID (string - UUID v4 without Hyphens)\n* userId : Publisher user ID (string - UUID v4 without Hyphens)\n* sessionId : Publisher session ID (string - UUID v4 without Hyphens)\n* timestamp : Event time (time.Time)\n* event_id : Event id. backward compatibility. (integer)\n* event_type : Event type. backward compatibility. (integer)\n* event_level : Event level. backward compatibility. (integer)\n* service : Service name. backward compatibility. (string)\n* client_ids : Client IDs. backward compatibility. ([]string - UUID v4 without Hyphens)\n* target_user_ids : Target user IDs. backward compatibility. ([]string - UUID v4 without Hyphens)\n* target_namespace : Target namespace. backward compatibility. (string)\n* privacy : Privacy. backward compatibility. (bool)\n* additional_fields : Set of data / object that given by producer. Each data have own key for specific purpose. Backward compatibility. (map[string]interface{}) \n* version : Event schema version (integer)\n* payload : Set of data / object that given by producer. Each data have own key for specific purpose. (map[string]interface{})\n\n## Publish Audit Log\n\nPublish or sent an audit log into stream. Client able to publish an audit log into single topic.\nPublish to `kafka` stream support with exponential backoff retry. (max 3x)\n\nEnvironment Variables:\n* APP_EVENT_STREAM_AUDIT_LOG_TOPIC(optional, default: auditLog)\n* APP_EVENT_STREAM_AUDIT_LOG_ENABLED(optional, default true)\n\nTo publish an audit log, use this function:\n```go\nerr := client.PublishAuditLog(eventstream.\n            NewAuditLogBuilder().\n            Category(Category).\n            ActionName(ActionName).\n            IP(IP).\n            Actor(Actor).\n            IsActorTypeUser(true).\n            ClientID(ClientID).\n            ActorNamespace(ActorNamespace).\n            ObjectID(ObjectID).\n\t        ObjectType(ObjectType)).\n            ObjectNamespace(ObjectNamespace).\n            TargetUserID(TargetUserID).\n            DeviceID(DeviceID).\n            Content(Content).\n            Diff(Diff).\n            ErrorCallback(func(message []byte, err error) {\n            })\n```\n\n#### Parameter\n* Category : Category. (string - Format: xxx_xxx - Required)\n* ActionName : Log action name. (string - Format: xxx_xxx - Required)\n* IP: IP address. (string - Optional)\n* Actor: Publisher/studio user id or client id. (string - UUID v4 without Hyphens - Required)\n* IsActorTypeUser: Is actor a user or not. (bool - true or false - Required)\n* ClientID : OAuth client ID. (string - UUID v4 without Hyphens - Required)\n* ActorNamespace : Actor namespace, should be publisher or studio namespace. (string - alphaNumeric(256) - Required)\n* ObjectID : Target resource id. (string - Optional)\n* ObjectType: Type of Object. (string - Optional)\n* ObjectNamespace : Namespace of target resource. (string - alphaNumeric(256) - Required)\n* TargetUserID : User id related to the resource. (string - UUID v4 without Hyphens - Optional)\n* DeviceID : Device id. (string - Optional)\n* Content : Resource Content. (map - Required)\n* Diff : Changes of the resource. (map - Recommended format: `{\"before\":{}, \"after\":{}}` - Optional)\n* ErrorCallback : Callback function when event failed to publish. (func(message []byte, err error){} - Optional)\n\n## SpanContext usage\n* Create Jaeger Span Context from an event\n```go\n\timport \"github.com/AccelByte/go-restful-plugins/v3/pkg/jaeger\"\n\n    spanContextString := event.SpanContext\n\tspan, ctx := jaeger.ChildSpanFromRemoteSpan(rootCtx, \"service-name.operation-name\", spanContextString)\n```\n\n* Put existing Jaeger Span Context into an event\n```go\n\timport \"github.com/AccelByte/go-restful-plugins/v3/pkg/jaeger\"\n\n    spanContextString := jaeger.GetSpanContextString(span)\n    \n    err := client.Register(\n        NewSubscribe().\n            Topic(topicName).\n            SpanContext(spanContextString).\n            // ...\n```\n\n# Tips\n## v3\n### Faster Write\n\nHere are some of the things you can do if you want to have faster writes.\n\n#### Set `RequiredAcks`\n\nFrom the `WriterConfig` documentation:\n\n\u003e Number of acknowledges from partition replicas required before receiving a response to a produce request. The default is -1, which means to wait for all replicas, and a value above 0 is required to indicate how many replicas should acknowledge a message to be considered successful.\n\nSet `RequiredAcks` to `1` so that it does not need to wait for all replicas to acknowledge.\n\nYou can set it up by injecting the `WriterConfig` inside `BrokerConfig` when creating new `KafkaClient`.\n\nNote that there's a gotcha in the library, you cannot set it to `0`, since it will be converted to `-1`, which is `RequireAll`.\n\n```go\n    if config.RequiredAcks == 0 {\n\t\tw.RequiredAcks = RequireAll\n\t}\n```\n\n#### Set `Async`\n\nFrom the `WriterConfig` documentation:\n\n\u003e Setting this flag to true causes the WriteMessages method to never block.\nIt also means that errors are ignored since the caller will not receive\nthe returned value. Use this only if you don't care about guarantees of\nwhether the messages were written to kafka.\n\nSet `Async` to `true` so that after the message is pushed into the writer's queue, the publishing function will return immediately.\n\nYou can set it up by injecting the `WriterConfig` inside `BrokerConfig` when creating new `KafkaClient`.\n\n#### Use more partitions\nSegmentio/kafka-go creates one `partitionWriter` per partition. So theoretically with more partitions, the more writer it has to parallelize the writing process.\n\n#### User more broker\nKafka will divide partitions between brokers, so with more brokers, each will handle less partition.\n\n### Handling Partition Change\n\nWhile by default segmentio/kafka-go can automatically rebalance Consumer Group assignments whenever there's a member change (e.g. new service pod is spawned), it has specific config to detect and handle partition change.\n\nFrom the `ReaderConfig` documentation:\n\n\u003e WatchForPartitionChanges is used to inform kafka-go that a consumer group should be\npolling the brokers and rebalancing if any partition changes happen to the topic.\n\nSet `WatchPartitionChanges` in `ReaderConfig` to true to tell the library to handle partition changes automatically. It can be injected inside `BrokerConfig` when creating new `KafkaClient`.\n\n# License\n    Copyright © 2020, AccelByte Inc. Released under the Apache License, Version 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faccelbyte%2Feventstream-go-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faccelbyte%2Feventstream-go-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faccelbyte%2Feventstream-go-sdk/lists"}