Dapr SDK for Go

This is the dapr SDK (client) for go (golang). It covers all of the APIs described in Dapr's protocol buffers with focus on developer productivity.

Installation

To install Dapr client package, you need to first install go and set up your development environment. To import Dapr go client in your code:

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

Quick start

package main

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

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

Assuming you have Dapr CLI installed locally, you can then launch your app like this:

dapr run --app-id my-app --protocol grpc --app-port 50001 go run main.go

See example folder for complete example.

Examples

Few common Dapr client usage examples

State

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

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

// save state with the key
err = client.SaveStateData(ctx, store, "k1", "v1", data)
handleErrors(err)

// get state for key
out, etag, err := client.GetState(ctx, store, "k1")
handleErrors(err)

// delete state for key
err = client.DeleteState(ctx, store, "k1")
handleErrors(err)

The StateItem type exposed by Dapr client provides more granular control options:

data := &client.StateItem{
    Etag:     "v1",
    Key:      "k1",
    Metadata: map[string]string{
        "key1": "value1",
        "key2": "value2",
    },
    Value:    []byte("hello"),
    Options:  &client.StateOptions{
        Concurrency: client.StateConcurrencyLastWrite,
        Consistency: client.StateConsistencyStrong,
        RetryPolicy: &client.StateRetryPolicy{
            Threshold: 3,
            Pattern: client.RetryPatternExponential,
            Interval: time.Duration(5 * time.Second),
        },
    },
}
err = client.SaveStateItem(ctx, store, data)

Similar StateOptions exist on GetDate and DeleteState methods. Additionally, Dapr client also provides a method to save multiple state items at once:

data := &client.State{
    StoreName: "my-store",
    States: []*client.StateItem{
        {
            Key:   "k1",
            Value: []byte("message 1"),
        },
        {
            Key:   "k2",
            Value: []byte("message 2"),
        },
    },
}
err = client.SaveState(ctx, data)

PubSub

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

data := []byte("hello")
err = client.PublishEvent(ctx, "topic-name", data)
handleErrors(err)

Service Invocation

To invoke a specific method on another service running with Dapr sidecar, the Dapr client provides two options. To invoke a service without any data:

resp, err = client.InvokeService(ctx, "service-name", "method-name") 
handleErrors(err)

And to invoke a service with data:

data := []byte("hello")
resp, err := client.InvokeServiceWithContent(ctx, "service-name", "method-name", "text/plain", data)
handleErrors(err)

Bindings

Similarly to Service, Dapr client provides two methods to invoke an operation on a Dapr-defined binding. Dapr supports input, output, and bidirectional bindings so the first methods supports all of them along with metadata options:

data := []byte("hello")
opt := map[string]string{
    "opt1": "value1",
    "opt2": "value2",
}
resp, meta, err := client.InvokeBinding(ctx, "binding-name", "operation-name", data, opt)
handleErrors(err)

And for simple, output only biding:

data := []byte("hello")
err = client.InvokeOutputBinding(ctx, "binding-name", "operation-name", data)
handleErrors(err)

Secrets

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)
handleErrors(err)

Contributing to Dapr go client

See the Contribution Guide to get started with building and developing.