Client library to help you build Dapr application in Go. This client supports all public Dapr APIs while focusing on idiomatic Go experience and developer productivity.
Assuming you already have installed Go
Dapr Go client includes two packages: client (for invoking public Dapr APIs), and service (to create services that will be invoked by Dapr, this is sometimes referred to as "callback").
With a correctly configured Go toolchain:
go get "github.com/dapr/go-sdk/client"Import Dapr Go client package:
import "github.com/dapr/go-sdk/client"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, see below for examples
}NewClient function has a default timeout for 5s, but you can customize this timeout by setting the environment variable DAPR_CLIENT_TIMEOUT_SECONDS.
For example:
package main
import (
"os"
dapr "github.com/dapr/go-sdk/client"
)
func main() {
os.Setenv("DAPR_CLIENT_TIMEOUT_SECONDS", "3")
client, err := dapr.NewClient()
if err != nil {
panic(err)
}
defer client.Close()
}Assuming you have Dapr CLI installed, you can then launch your app locally like this:
dapr run --app-id example-service \
--app-protocol grpc \
--app-port 50001 \
go run main.goSee the example folder for more working Dapr client examples.
The Go client supports all the building blocks exposed by Dapr API. Let's review these one by one:
For simple use-cases, Dapr client provides easy to use Save, Get, and 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 used 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)To publish data onto a topic, the Dapr 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 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.InvokeMethod(ctx, "app-id", "method-name", "post")And to 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)Similarly to Service, Dapr client 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)The Dapr client also provides access to the runtime secrets that can be backed by any number of secret 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)The Dapr client provides methods to grab a distributed lock and unlock it.
Grab a lock:
ctx := context.Background()
store := "my-store" // defined in the component YAML
r, err := testClient.TryLockAlpha1(ctx, testLockStore, &LockRequest{
LockOwner: "owner1",
ResourceID: "resource1",
ExpiryInSeconds: 5,
})Unlock a lock:
r, err := testClient.UnlockAlpha1(ctx, testLockStore, &UnlockRequest{
LockOwner: "owner1",
ResourceID: "resource1",
})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:
If the DAPR_API_TOKEN environment variable is defined, Dapr will automatically use it to augment its Dapr API invocations to ensure authentication.
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")
}Dapr errors are based on gRPC's richer error model. The following code shows how to 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)
}
}
}In addition to the client capabilities that allow you to call into the Dapr API, the Go SDK also provides service package to help you bootstrap Dapr callback services in either gRPC or HTTP. Instructions on how to use it are located here.
See the Contribution Guide to get started with building and developing.
Please refer to our Dapr Community Code of Conduct.
