This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Dapr Go SDK

Go SDK packages for developing Dapr applications

1: Getting started with the Dapr client Go SDK

2: Getting started with the Dapr Service (Callback) SDK for Go

2.1: Getting started with the Dapr HTTP Service SDK for Go
2.2: Getting started with the Dapr Service (Callback) SDK for Go

A client library to help build Dapr applications in Go. This client supports all public Dapr APIs while focusing on idiomatic Go experiences and developer productivity.

Client

Use the Go Client SDK for invoking public Dapr APIs

Learn more about the Go Client SDK

Service

Use the Dapr Service (Callback) SDK for Go to create services that will be invoked by Dapr.

Learn more about the Go Service (Callback) SDK

1 - Getting started with the Dapr client Go SDK

How to get up and running with the Dapr Go SDK

The Dapr client package allows you to interact with other Dapr applications from a Go application.

Prerequisites

Dapr CLI installed
Initialized Dapr environment
Go installed

Import the client package

import "github.com/dapr/go-sdk/client"

Error handling

Dapr errors are based on gRPC’s richer error model. The following code shows an example of how you can parse and handle the error details:

if err != nil {
    st := status.Convert(err)

    fmt.Printf("Code: %s\n", st.Code().String())
    fmt.Printf("Message: %s\n", st.Message())

    for _, detail := range st.Details() {
        switch t := detail.(type) {
        case *errdetails.ErrorInfo:
            // Handle ErrorInfo details
            fmt.Printf("ErrorInfo:\n- Domain: %s\n- Reason: %s\n- Metadata: %v\n", t.GetDomain(), t.GetReason(), t.GetMetadata())
        case *errdetails.BadRequest:
            // Handle BadRequest details
            fmt.Println("BadRequest:")
            for _, violation := range t.GetFieldViolations() {
                fmt.Printf("- Key: %s\n", violation.GetField())
                fmt.Printf("- The %q field was wrong: %s\n", violation.GetField(), violation.GetDescription())
            }
        case *errdetails.ResourceInfo:
            // Handle ResourceInfo details
            fmt.Printf("ResourceInfo:\n- Resource type: %s\n- Resource name: %s\n- Owner: %s\n- Description: %s\n",
                t.GetResourceType(), t.GetResourceName(), t.GetOwner(), t.GetDescription())
        case *errdetails.Help:
            // Handle ResourceInfo details
            fmt.Println("HelpInfo:")
            for _, link := range t.GetLinks() {
                fmt.Printf("- Url: %s\n", link.Url)
                fmt.Printf("- Description: %s\n", link.Description)
            }

        default:
            // Add cases for other types of details you expect
            fmt.Printf("Unhandled error detail type: %v\n", t)
        }
    }
}

Building blocks

The Go SDK allows you to interface with all of the Dapr building blocks.

Service Invocation

To invoke a specific method on another service running with Dapr sidecar, the Dapr client Go SDK provides two options:

Invoke a service without data:

resp, err := client.InvokeMethod(ctx, "app-id", "method-name", "post")

Invoke a service with data:

content := &dapr.DataContent{
    ContentType: "application/json",
    Data:        []byte(`{ "id": "a123", "value": "demo", "valid": true }`),
}

resp, err = client.InvokeMethodWithContent(ctx, "app-id", "method-name", "post", content)

For a full guide on service invocation, visit How-To: Invoke a service.

Workflows

Workflows and their activities can be authored and managed using the Dapr Go SDK like so:

import (
	"context"
	"fmt"
	"log"

	"github.com/dapr/durabletask-go/workflow"
	dapr "github.com/dapr/go-sdk/client"
)

func ExampleWorkflow(ctx *workflow.WorkflowContext) (any, error) {
	var output string
	input := "world"

	if err := ctx.CallActivity(ExampleActivity, workflow.WithActivityInput(input)).Await(&output); err != nil {
		return nil, err
	}

	// Print output - "hello world"
	fmt.Println(output)

	return nil, nil
}

func ExampleActivity(ctx workflow.ActivityContext) (any, error) {
	var input int
	if err := ctx.GetInput(&input); err != nil {
		return "", err
	}

	return fmt.Sprintf("hello %s", input), nil
}

func main() {
	r := workflow.NewRegistry()

	// Register the workflow
	r.AddWorkflow(ExampleWorkflow)

	// Register the activity
	r.AddActivity(ExampleActivity)

	client, err := dapr.NewWorkflowClient()
	if err != nil {
		log.Fatal(err)
	}

	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()
	if err := client.StartWorker(ctx, r); err != nil {
		log.Fatal(err)
	}

	// Start a new workflow
	id, err := client.ScheduleWorkflow(ctx, "ExampleWorkflow")
	if err != nil {
		log.Fatal(err)
	}

	// Wait for the workflow to complete
	metadata, err := client.WaitForWorkflowCompletion(ctx, id)
	if err != nil {
		log.Fatal(err)
	}

	// Print workflow status post-completion
	fmt.Println(metadata.String())
}

Managing workflows

The workflow client returned by dapr.NewWorkflowClient() also exposes the management operations: SuspendWorkflow, ResumeWorkflow, TerminateWorkflow, PurgeWorkflowState, RaiseEvent and FetchWorkflowMetadata, plus the advanced operations below.

Listing workflow instances

ListInstanceIDs returns the workflow instance IDs belonging to the app. Results are paginated: the page size is an upper bound on how many IDs a page carries, and you keep calling with the continuation token from the previous response until it comes back nil.

var token string
for {
	opts := []workflow.ListInstanceIDsOptions{
		workflow.WithListInstanceIDsPageSize(100),
	}
	if token != "" {
		opts = append(opts, workflow.WithListInstanceIDsContinuationToken(token))
	}

	resp, err := client.ListInstanceIDs(ctx, opts...)
	if err != nil {
		log.Fatal(err)
	}

	for _, id := range resp.InstanceIds {
		fmt.Println(id)
	}

	if resp.ContinuationToken == nil {
		break
	}
	token = *resp.ContinuationToken
}

This requires a state store with actor support that can list keys.

Reading a workflow’s history

GetInstanceHistory returns the full execution history of an instance, which is useful for auditing a run or for finding an event to rerun from.

hist, err := client.GetInstanceHistory(ctx, id)
if err != nil {
	log.Fatal(err)
}

var rerunFrom uint32
for _, event := range hist.Events {
	if ts := event.GetTaskScheduled(); ts != nil {
		fmt.Printf("event %d scheduled activity %s\n", event.GetEventId(), ts.GetName())

		// History event IDs are int32 and some event types carry -1, while
		// RerunWorkflowFromEvent takes a uint32, so narrow before reusing it.
		if id := event.GetEventId(); id >= 0 {
			rerunFrom = uint32(id)
		}
	}
}

The call returns NotFound if the instance does not exist or its state has been purged.

Rerunning a workflow from an event

RerunWorkflowFromEvent reruns (“rewinds”) a completed workflow from one of its history events into a new instance. The source instance is left untouched.

Work that had already completed and been recorded before the target event is replayed from history rather than executed again. Everything else from before the target event is re-executed in the new instance: activities that were still in flight, timers that had not fired, and child workflows that had not finished. Note that in a parallel workflow this includes an activity that succeeded but whose completion was recorded after the target event — so a fan-out reruns more than you might expect. Plan for re-execution if your activities are not idempotent.

newID, err := client.RerunWorkflowFromEvent(ctx, id, eventID,
	workflow.WithRerunNewInstanceID("my-rerun"),
	workflow.WithRerunInput(newInput),
)
if err != nil {
	log.Fatal(err)
}

metadata, err := client.WaitForWorkflowCompletion(ctx, newID)
if err != nil {
	log.Fatal(err)
}
fmt.Println(metadata.String())

Things to know:

The source instance must be in a terminal state. Rerunning a running instance fails with InvalidArgument.
The source cannot itself be a child workflow — that also fails with InvalidArgument.
Only three event types can be rerun: TaskScheduled (a scheduled activity), TimerCreated and ChildWorkflowInstanceCreated. Any other event is rejected with NotFound.
eventID is the event’s own ID, not its index in the history slice.
WithRerunInput replaces the input of the target event only. It is invalid on a timer event.
WithRerunNewChildInstanceID is only valid on a child-workflow event.
If WithRerunNewInstanceID is omitted, the runtime generates a new instance ID. If it is given, it must differ from the source ID and must not already have state, otherwise the call fails with InvalidArgument or AlreadyExists.
For a more comprehensive guide on workflows visit these How-To guides:
- How-To: Author a workflow.
- How-To: Manage a workflow.
Visit the Go SDK Examples to jump into complete examples:
- Workflow Example
- Workflow - Parallelised

State Management

For simple use-cases, Dapr client provides easy to use Save, Get, Delete methods:

ctx := context.Background()
data := []byte("hello")
store := "my-store" // defined in the component YAML

// save state with the key key1, default options: strong, last-write
if err := client.SaveState(ctx, store, "key1", data, nil); err != nil {
    panic(err)
}

// get state for key key1
item, err := client.GetState(ctx, store, "key1", nil)
if err != nil {
    panic(err)
}
fmt.Printf("data [key:%s etag:%s]: %s", item.Key, item.Etag, string(item.Value))

// delete state for key key1
if err := client.DeleteState(ctx, store, "key1", nil); err != nil {
    panic(err)
}

For more granular control, the Dapr Go client exposes SetStateItem type, which can be use to gain more control over the state operations and allow for multiple items to be saved at once:

item1 := &dapr.SetStateItem{
    Key:  "key1",
    Etag: &ETag{
        Value: "1",
    },
    Metadata: map[string]string{
        "created-on": time.Now().UTC().String(),
    },
    Value: []byte("hello"),
    Options: &dapr.StateOptions{
        Concurrency: dapr.StateConcurrencyLastWrite,
        Consistency: dapr.StateConsistencyStrong,
    },
}

item2 := &dapr.SetStateItem{
    Key:  "key2",
    Metadata: map[string]string{
        "created-on": time.Now().UTC().String(),
    },
    Value: []byte("hello again"),
}

item3 := &dapr.SetStateItem{
    Key:  "key3",
    Etag: &dapr.ETag{
	Value: "1",
    },
    Value: []byte("hello again"),
}

if err := client.SaveBulkState(ctx, store, item1, item2, item3); err != nil {
    panic(err)
}

Similarly, GetBulkState method provides a way to retrieve multiple state items in a single operation:

keys := []string{"key1", "key2", "key3"}
items, err := client.GetBulkState(ctx, store, keys, nil,100)

And the ExecuteStateTransaction method to execute multiple upsert or delete operations transactionally.

ops := make([]*dapr.StateOperation, 0)

op1 := &dapr.StateOperation{
    Type: dapr.StateOperationTypeUpsert,
    Item: &dapr.SetStateItem{
        Key:   "key1",
        Value: []byte(data),
    },
}
op2 := &dapr.StateOperation{
    Type: dapr.StateOperationTypeDelete,
    Item: &dapr.SetStateItem{
        Key:   "key2",
    },
}
ops = append(ops, op1, op2)
meta := map[string]string{}
err := testClient.ExecuteStateTransaction(ctx, store, meta, ops)

Retrieve, filter, and sort key/value data stored in your statestore using QueryState.

// Define the query string
query := `{
	"filter": {
		"EQ": { "value.Id": "1" }
	},
	"sort": [
		{
			"key": "value.Balance",
			"order": "DESC"
		}
	]
}`

// Use the client to query the state
queryResponse, err := c.QueryState(ctx, "querystore", query)
if err != nil {
	log.Fatal(err)
}

fmt.Printf("Got %d\n", len(queryResponse))

for _, account := range queryResponse {
	var data Account
	err := account.Unmarshal(&data)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Account: %s has %f\n", data.ID, data.Balance)
}

Note: Query state API is currently in alpha

For a full guide on state management, visit How-To: Save & get state.

Publish Messages

To publish data onto a topic, the Dapr Go client provides a simple method:

data := []byte(`{ "id": "a123", "value": "abcdefg", "valid": true }`)
if err := client.PublishEvent(ctx, "component-name", "topic-name", data); err != nil {
    panic(err)
}

To publish multiple messages at once, the PublishEvents method can be used:

events := []string{"event1", "event2", "event3"}
res := client.PublishEvents(ctx, "component-name", "topic-name", events)
if res.Error != nil {
    panic(res.Error)
}

For a full guide on pub/sub, visit How-To: Publish & subscribe.

Workflow

You can create workflows using the Go SDK. For example, start with a simple workflow activity:

func TestActivity(ctx workflow.ActivityContext) (any, error) {
	var input int
	if err := ctx.GetInput(&input); err != nil {
		return "", err
	}

	// Do something here
	return "result", nil
}

Write a simple workflow function:

func TestWorkflow(ctx *workflow.WorkflowContext) (any, error) {
	var input int
	if err := ctx.GetInput(&input); err != nil {
		return nil, err
	}
	var output string
	if err := ctx.CallActivity(TestActivity, workflow.ActivityInput(input)).Await(&output); err != nil {
		return nil, err
	}
	if err := ctx.WaitForExternalEvent("testEvent", time.Second*60).Await(&output); err != nil {
		return nil, err
	}

	if err := ctx.CreateTimer(time.Second).Await(nil); err != nil {
		return nil, nil
	}
	return output, nil
}

To wait for the first of several tasks to complete, use ctx.Select. It returns the index of the task that completed first. For example, an approval gate waits for an Approve event, a Reject event or a timeout, whichever comes first:

func ApprovalWorkflow(ctx *workflow.WorkflowContext) (any, error) {
	// A negative timeout waits for the event without a time limit
	approve := ctx.WaitForExternalEvent("Approve", -1)
	reject := ctx.WaitForExternalEvent("Reject", -1)
	timeout := ctx.CreateTimer(24 * time.Hour)

	winner, err := ctx.Select(approve, reject, timeout)
	if err != nil {
		return nil, err
	}

	switch winner {
	case 0:
		var approver string
		if err := approve.Await(&approver); err != nil {
			return nil, err
		}
		return "approved by " + approver, nil
	case 1:
		return "rejected", nil
	default:
		return "timed out", nil
	}
}

Without Select, a workflow has to poll each event with short WaitForExternalEvent timeouts, and every poll adds a timer and a history entry. Select itself adds no timers or history entries, so a workflow that waits at a gate does not grow its history. The tasks that lose stay pending, and you can await them or pass them to a later Select. When you select on the same event name in a loop, pass the pending task to the next Select instead of calling WaitForExternalEvent again for that name. Select needs Go SDK v1.16.0 or later, which uses durabletask-go v0.15.0 or later.

Then compose your application that will use the workflow you’ve created. Refer to the How-To: Author workflows guide for a full walk-through.

Try out the Go SDK workflow example.

Jobs

The Dapr client Go SDK allows you to schedule, get, and delete jobs. Jobs enable you to schedule work to be executed at specific times or intervals.

Scheduling a Job

To schedule a new job, use the ScheduleJob method:

import (
    "google.golang.org/protobuf/types/known/anypb"
)

// Create job data
data, err := anypb.New(&YourDataStruct{Message: "Hello, Job!"})
if err != nil {
    panic(err)
}

// Create a simple job using the builder pattern
job := client.NewJob("my-scheduled-job",
    client.WithJobData(data),
    client.WithJobDueTime("10s"), // Execute in 10 seconds
)

// Schedule the job
err = client.ScheduleJob(ctx, job)
if err != nil {
    panic(err)
}

Job with Schedule and Repeats

You can create recurring jobs using the Schedule field with cron expressions:

job := client.NewJob("recurring-job",
    client.WithJobData(data),
    client.WithJobSchedule("0 9 * * *"), // Run at 9 AM every day
    client.WithJobRepeats(10),            // Repeat 10 times
    client.WithJobTTL("1h"),              // Job expires after 1 hour
)

err = client.ScheduleJob(ctx, job)

Job with Failure Policy

Configure how jobs should handle failures using failure policies:

// Constant retry policy with max retries and interval
job := client.NewJob("resilient-job",
    client.WithJobData(data),
    client.WithJobDueTime("2024-01-01T10:00:00Z"),
    client.WithJobConstantFailurePolicy(),
    client.WithJobConstantFailurePolicyMaxRetries(3),
    client.WithJobConstantFailurePolicyInterval(30*time.Second),
)

err = client.ScheduleJob(ctx, job)

For jobs that should not be retried on failure, use the drop policy:

job := client.NewJob("one-shot-job",
    client.WithJobData(data),
    client.WithJobDueTime("2024-01-01T10:00:00Z"),
    client.WithJobDropFailurePolicy(),
)

err = client.ScheduleJob(ctx, job)

Getting a Job

To get information about a scheduled job:

job, err := client.GetJob(ctx, "my-scheduled-job")
if err != nil {
    panic(err)
}

fmt.Printf("Job: %s, Schedule: %s, Repeats: %d\n",
    job.Name, job.Schedule, job.Repeats)

Deleting a Job

To cancel a scheduled job:

err = client.DeleteJob(ctx, "my-scheduled-job")
if err != nil {
    panic(err)
}

For a full guide on jobs, visit How-To: Schedule and manage jobs.

Output Bindings

The Dapr Go client SDK provides two methods to invoke an operation on a Dapr-defined binding. Dapr supports input, output, and bidirectional bindings.

For simple, output-only binding:

in := &dapr.InvokeBindingRequest{ Name: "binding-name", Operation: "operation-name" }
err = client.InvokeOutputBinding(ctx, in)

To invoke method with content and metadata:

in := &dapr.InvokeBindingRequest{
    Name:      "binding-name",
    Operation: "operation-name",
    Data: []byte("hello"),
    Metadata: map[string]string{"k1": "v1", "k2": "v2"},
}

out, err := client.InvokeBinding(ctx, in)

For a full guide on output bindings, visit How-To: Use bindings.

Actors

Use the Dapr Go client SDK to write actors.

// MyActor represents an example actor type.
type MyActor struct {
	actors.Actor
}

// MyActorMethod is a method that can be invoked on MyActor.
func (a *MyActor) MyActorMethod(ctx context.Context, req *actors.Message) (string, error) {
	log.Printf("Received message: %s", req.Data)
	return "Hello from MyActor!", nil
}

func main() {
	// Create a Dapr client
	daprClient, err := client.NewClient()
	if err != nil {
		log.Fatal("Error creating Dapr client: ", err)
	}

	// Register the actor type with Dapr
	actors.RegisterActor(&MyActor{})

	// Create an actor client
	actorClient := actors.NewClient(daprClient)

	// Create an actor ID
	actorID := actors.NewActorID("myactor")

	// Get or create the actor
	err = actorClient.SaveActorState(context.Background(), "myactorstore", actorID, map[string]interface{}{"data": "initial state"})
	if err != nil {
		log.Fatal("Error saving actor state: ", err)
	}

	// Invoke a method on the actor
	resp, err := actorClient.InvokeActorMethod(context.Background(), "myactorstore", actorID, "MyActorMethod", &actors.Message{Data: []byte("Hello from client!")})
	if err != nil {
		log.Fatal("Error invoking actor method: ", err)
	}

	log.Printf("Response from actor: %s", resp.Data)

	// Wait for a few seconds before terminating
	time.Sleep(5 * time.Second)

	// Delete the actor
	err = actorClient.DeleteActor(context.Background(), "myactorstore", actorID)
	if err != nil {
		log.Fatal("Error deleting actor: ", err)
	}

	// Close the Dapr client
	daprClient.Close()
}

For a full guide on actors, visit the Actors building block documentation.

Host actors over gRPC (Alpha)

From Go SDK v1.16.0, the app can host actors over gRPC instead of an HTTP callback server. SubscribeActorEvents registers the actor types of the actor runtime with the Dapr sidecar and receives actor method invocations, reminders, timers and deactivations on one bidirectional stream (SubscribeActorEventsAlpha1). It reconnects and registers the actor types again when the stream fails. Use it when the app should not expose HTTP endpoints for actor callbacks. If the sidecar has an app port, run it with --app-protocol grpc: the sidecar rejects the stream when the app channel is HTTP.

// MyActor embeds actor.ServerImplBaseCtx and implements Type().
// Register the actor types on the actor runtime, as for HTTP hosting.
rt := runtime.GetActorRuntimeInstanceContext()
rt.RegisterActorFactory(func() actor.ServerContext { return &MyActor{} })

// Receive the actor callbacks over the actor event stream.
stop, err := daprClient.SubscribeActorEvents(ctx, rt, client.ActorEventSubscriptionOptions{
	ActorIdleTimeout: time.Hour,
})
if err != nil {
	log.Fatal("Error subscribing to actor events: ", err)
}
defer stop()

Learn more in Actor app-initiated gRPC event streams, and try the Go SDK gRPC actor example.

Secret Management

The Dapr client also provides access to the runtime secrets that can be backed by any number of secrete stores (e.g. Kubernetes Secrets, HashiCorp Vault, or Azure KeyVault):

opt := map[string]string{
    "version": "2",
}

secret, err := client.GetSecret(ctx, "store-name", "secret-name", opt)

Authentication

By default, Dapr relies on the network boundary to limit access to its API. If however the target Dapr API is configured with token-based authentication, users can configure the Go Dapr client with that token in two ways:

Environment Variable

If the DAPR_API_TOKEN environment variable is defined, Dapr will automatically use it to augment its Dapr API invocations to ensure authentication.

Explicit Method

In addition, users can also set the API token explicitly on any Dapr client instance. This approach is helpful in cases when the user code needs to create multiple clients for different Dapr API endpoints.

func main() {
    client, err := dapr.NewClient()
    if err != nil {
        panic(err)
    }
    defer client.Close()
    client.WithAuthToken("your-Dapr-API-token-here")
}

For a full guide on secrets, visit How-To: Retrieve secrets.

Distributed Lock

The Dapr client provides mutually exclusive access to a resource using a lock. With a lock, you can:

Provide access to a database row, table, or an entire database
Lock reading messages from a queue in a sequential manner

package main

import (
    "fmt"

    dapr "github.com/dapr/go-sdk/client"
)

func main() {
    client, err := dapr.NewClient()
    if err != nil {
        panic(err)
    }
    defer client.Close()

    resp, err := client.TryLockAlpha1(ctx, "lockstore", &dapr.LockRequest{
			LockOwner:         "random_id_abc123",
			ResourceID:      "my_file_name",
			ExpiryInSeconds: 60,
		})

    fmt.Println(resp.Success)
}

For a full guide on distributed lock, visit How-To: Use a lock.

Configuration

With the Dapr client Go SDK, you can consume configuration items that are returned as read-only key/value pairs, and subscribe to configuration item changes.

Config Get

	items, err := client.GetConfigurationItem(ctx, "example-config", "mykey")
	if err != nil {
		panic(err)
	}
	fmt.Printf("get config = %s\n", (*items).Value)

go func() {
	if err := client.SubscribeConfigurationItems(ctx, "example-config", []string{"mySubscribeKey1", "mySubscribeKey2", "mySubscribeKey3"}, func(id string, items map[string]*dapr.ConfigurationItem) {
		for k, v := range items {
			fmt.Printf("get updated config key = %s, value = %s \n", k, v.Value)
		}
		subscribeID = id
	}); err != nil {
		panic(err)
	}
}()

For a full guide on configuration, visit How-To: Manage configuration from a store.

Cryptography

With the Dapr client Go SDK, you can use the high-level Encrypt and Decrypt cryptography APIs to encrypt and decrypt files while working on a stream of data.

To encrypt:

// Encrypt the data using Dapr
out, err := client.Encrypt(context.Background(), rf, dapr.EncryptOptions{
	// These are the 3 required parameters
	ComponentName: "mycryptocomponent",
	KeyName:        "mykey",
	Algorithm:     "RSA",
})
if err != nil {
	panic(err)
}

To decrypt:

// Decrypt the data using Dapr
out, err := client.Decrypt(context.Background(), rf, dapr.EncryptOptions{
	// Only required option is the component name
	ComponentName: "mycryptocomponent",
})

For a full guide on cryptography, visit How-To: Use the cryptography APIs.

Go SDK Examples

2 - Getting started with the Dapr Service (Callback) SDK for Go

How to get up and running with the Dapr Service (Callback) SDK for Go

In addition to this Dapr API client, Dapr Go SDK also provides service package to bootstrap your Dapr callback services. These services can be developed in either gRPC or HTTP:

2.1 - Getting started with the Dapr HTTP Service SDK for Go

How to get up and running with the Dapr HTTP Service SDK for Go

Prerequisite

Start by importing Dapr Go service/http package:

daprd "github.com/dapr/go-sdk/service/http"

Creating and Starting Service

To create an HTTP Dapr service, first, create a Dapr callback instance with a specific address:

s := daprd.NewService(":8080")

Or with address and an existing http.ServeMux in case you want to combine existing server implementations:

mux := http.NewServeMux()
mux.HandleFunc("/", myOtherHandler)
s := daprd.NewServiceWithMux(":8080", mux)

Once you create a service instance, you can “attach” to that service any number of event, binding, and service invocation logic handlers as shown below. Onces the logic is defined, you are ready to start the service:

if err := s.Start(); err != nil && err != http.ErrServerClosed {
	log.Fatalf("error: %v", err)
}

Event Handling

To handle events from specific topic you need to add at least one topic event handler before starting the service:

sub := &common.Subscription{
	PubsubName: "messages",
	Topic:      "topic1",
	Route:      "/events",
}
err := s.AddTopicEventHandler(sub, eventHandler)
if err != nil {
	log.Fatalf("error adding topic subscription: %v", err)
}

The handler method itself can be any method with the expected signature:

func eventHandler(ctx context.Context, e *common.TopicEvent) (retry bool, err error) {
	log.Printf("event - PubsubName:%s, Topic:%s, ID:%s, Data: %v", e.PubsubName, e.Topic, e.ID, e.Data)
	// do something with the event
	return true, nil
}

Optionally, you can use routing rules to send messages to different handlers based on the contents of the CloudEvent.

sub := &common.Subscription{
	PubsubName: "messages",
	Topic:      "topic1",
	Route:      "/important",
	Match:      `event.type == "important"`,
	Priority:   1,
}
err := s.AddTopicEventHandler(sub, importantHandler)
if err != nil {
	log.Fatalf("error adding topic subscription: %v", err)
}

You can also create a custom type that implements the TopicEventSubscriber interface to handle your events:

type EventHandler struct {
	// any data or references that your event handler needs.
}

func (h *EventHandler) Handle(ctx context.Context, e *common.TopicEvent) (retry bool, err error) {
    log.Printf("event - PubsubName:%s, Topic:%s, ID:%s, Data: %v", e.PubsubName, e.Topic, e.ID, e.Data)
    // do something with the event
    return true, nil
}

The EventHandler can then be added using the AddTopicEventSubscriber method:

sub := &common.Subscription{
    PubsubName: "messages",
    Topic:      "topic1",
}
eventHandler := &EventHandler{
// initialize any fields
}
if err := s.AddTopicEventSubscriber(sub, eventHandler); err != nil {
    log.Fatalf("error adding topic subscription: %v", err)
}

Service Invocation Handler

To handle service invocations you will need to add at least one service invocation handler before starting the service:

if err := s.AddServiceInvocationHandler("/echo", echoHandler); err != nil {
	log.Fatalf("error adding invocation handler: %v", err)
}

The handler method itself can be any method with the expected signature:

func echoHandler(ctx context.Context, in *common.InvocationEvent) (out *common.Content, err error) {
	log.Printf("echo - ContentType:%s, Verb:%s, QueryString:%s, %+v", in.ContentType, in.Verb, in.QueryString, string(in.Data))
	// do something with the invocation here 
	out = &common.Content{
		Data:        in.Data,
		ContentType: in.ContentType,
		DataTypeURL: in.DataTypeURL,
	}
	return
}

Binding Invocation Handler

if err := s.AddBindingInvocationHandler("/run", runHandler); err != nil {
	log.Fatalf("error adding binding handler: %v", err)
}

The handler method itself can be any method with the expected signature:

func runHandler(ctx context.Context, in *common.BindingEvent) (out []byte, err error) {
	log.Printf("binding - Data:%v, Meta:%v", in.Data, in.Metadata)
	// do something with the invocation here 
	return nil, nil
}

Go SDK Examples

2.2 - Getting started with the Dapr Service (Callback) SDK for Go

How to get up and running with the Dapr Service (Callback) SDK for Go

Dapr gRPC Service SDK for Go

Prerequisite

Start by importing Dapr Go service/grpc package:

daprd "github.com/dapr/go-sdk/service/grpc"

Creating and Starting Service

To create a gRPC Dapr service, first, create a Dapr callback instance with a specific address:

s, err := daprd.NewService(":50001")
if err != nil {
    log.Fatalf("failed to start the server: %v", err)
}

Or with address and an existing net.Listener in case you want to combine existing server listener:

list, err := net.Listen("tcp", "localhost:0")
if err != nil {
	log.Fatalf("gRPC listener creation failed: %s", err)
}
s := daprd.NewServiceWithListener(list)

if err := s.Start(); err != nil {
    log.Fatalf("server error: %v", err)
}

Event Handling

To handle events from specific topic you need to add at least one topic event handler before starting the service:

sub := &common.Subscription{
		PubsubName: "messages",
		Topic:      "topic1",
	}
if err := s.AddTopicEventHandler(sub, eventHandler); err != nil {
    log.Fatalf("error adding topic subscription: %v", err)
}

The handler method itself can be any method with the expected signature:

func eventHandler(ctx context.Context, e *common.TopicEvent) (retry bool, err error) {
	log.Printf("event - PubsubName:%s, Topic:%s, ID:%s, Data: %v", e.PubsubName, e.Topic, e.ID, e.Data)
	// do something with the event
	return true, nil
}

Optionally, you can use routing rules to send messages to different handlers based on the contents of the CloudEvent.

sub := &common.Subscription{
	PubsubName: "messages",
	Topic:      "topic1",
	Route:      "/important",
	Match:      `event.type == "important"`,
	Priority:   1,
}
err := s.AddTopicEventHandler(sub, importantHandler)
if err != nil {
	log.Fatalf("error adding topic subscription: %v", err)
}

You can also create a custom type that implements the TopicEventSubscriber interface to handle your events:

type EventHandler struct {
	// any data or references that your event handler needs.
}

func (h *EventHandler) Handle(ctx context.Context, e *common.TopicEvent) (retry bool, err error) {
    log.Printf("event - PubsubName:%s, Topic:%s, ID:%s, Data: %v", e.PubsubName, e.Topic, e.ID, e.Data)
    // do something with the event
    return true, nil
}

The EventHandler can then be added using the AddTopicEventSubscriber method:

sub := &common.Subscription{
    PubsubName: "messages",
    Topic:      "topic1",
}
eventHandler := &EventHandler{
// initialize any fields
}
if err := s.AddTopicEventSubscriber(sub, eventHandler); err != nil {
    log.Fatalf("error adding topic subscription: %v", err)
}

Service Invocation Handler

To handle service invocations you will need to add at least one service invocation handler before starting the service:

if err := s.AddServiceInvocationHandler("echo", echoHandler); err != nil {
    log.Fatalf("error adding invocation handler: %v", err)
}

The handler method itself can be any method with the expected signature:

func echoHandler(ctx context.Context, in *common.InvocationEvent) (out *common.Content, err error) {
	log.Printf("echo - ContentType:%s, Verb:%s, QueryString:%s, %+v", in.ContentType, in.Verb, in.QueryString, string(in.Data))
	// do something with the invocation here 
	out = &common.Content{
		Data:        in.Data,
		ContentType: in.ContentType,
		DataTypeURL: in.DataTypeURL,
	}
	return
}

Binding Invocation Handler

To handle binding invocations you will need to add at least one binding invocation handler before starting the service:

if err := s.AddBindingInvocationHandler("run", runHandler); err != nil {
    log.Fatalf("error adding binding handler: %v", err)
}

The handler method itself can be any method with the expected signature:

func runHandler(ctx context.Context, in *common.BindingEvent) (out []byte, err error) {
	log.Printf("binding - Data:%v, Meta:%v", in.Data, in.Metadata)
	// do something with the invocation here 
	return nil, nil
}

Go SDK Examples

Dapr Go SDK

Client

Service

1 - Getting started with the Dapr client Go SDK

Prerequisites

Import the client package

Error handling

Building blocks

Service Invocation

Workflows

Managing workflows

Listing workflow instances

Reading a workflow’s history

Rerunning a workflow from an event

State Management

Publish Messages

Workflow

Jobs

Scheduling a Job

Job with Schedule and Repeats

Job with Failure Policy

Getting a Job

Deleting a Job

Output Bindings

Actors

Host actors over gRPC (Alpha)

Secret Management

Authentication

Distributed Lock

Configuration

Config Get

Config Subscribe

Cryptography

Related links

2 - Getting started with the Dapr Service (Callback) SDK for Go

2.1 - Getting started with the Dapr HTTP Service SDK for Go

Prerequisite

Creating and Starting Service

Event Handling

Service Invocation Handler

Binding Invocation Handler

Related links

2.2 - Getting started with the Dapr Service (Callback) SDK for Go

Dapr gRPC Service SDK for Go

Prerequisite

Creating and Starting Service

Event Handling

Service Invocation Handler

Binding Invocation Handler

Related links