• Stars
    star
    443
  • Rank 98,504 (Top 2 %)
  • Language
    Go
  • License
    Apache License 2.0
  • Created about 5 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Dapr SDK for go

Dapr SDK for Go

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.

Test Release Go Report Card GitHub go.mod Go version codecov FOSSA Status

Usage

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").

Creating client

Import Dapr Go client package:

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, 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.go

See the example folder for more working Dapr client examples.

Usage

The Go client supports all the building blocks exposed by Dapr API. Let's review these one by one:

State

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)
PubSub

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)
}
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.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)
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.

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)
Secrets

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)
Distributed Lock

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",
})
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")
}

Service (callback)

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.

Contributing to Dapr Go client

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

Code of Conduct

Please refer to our Dapr Community Code of Conduct.

More Repositories

1

dapr

Dapr is a portable, event-driven, runtime for building distributed applications across cloud and edge.
Go
23,824
star
2

dotnet-sdk

Dapr SDK for .NET
C#
1,107
star
3

quickstarts

Dapr quickstart code samples and tutorials showcasing core Dapr capabilities
Java
1,027
star
4

docs

Dapr user documentation, used to build docs.dapr.io
HTML
992
star
5

components-contrib

Community driven, reusable components for distributed apps
Go
543
star
6

samples

Community driven repository for Dapr samples
JavaScript
412
star
7

cli

Command-line tools for Dapr.
Go
317
star
8

java-sdk

Dapr SDK for Java
Java
258
star
9

python-sdk

Dapr SDK for Python
Python
222
star
10

rust-sdk

Dapr SDK for Rust - Alpha
Rust
212
star
11

js-sdk

Dapr SDK for Javascript
JavaScript
197
star
12

dashboard

General purpose dashboard for Dapr
Go
181
star
13

community

Governance and community material for Dapr and its open source sub-projects
140
star
14

php-sdk

Dapr SDK for PHP
PHP
70
star
15

dapr-shared

Dapr Shared enables users to deploy Dapr as a DaemonSet or a Deployment instead of a sidecar
Go
48
star
16

installer-bundle

Dapr bundled installer containing CLI and runtime packaged together. This eliminated the need to download Docker images when initializing Dapr locally.
36
star
17

cpp-sdk

C++ SDK for Dapr
Makefile
36
star
18

helm-charts

Helm Charts for Dapr
20
star
19

mechanical-markdown

Python
20
star
20

kit

Shared utility code for Dapr runtime
Go
19
star
21

sig-api

Repository for Dapr API Special Interest Group
HTML
18
star
22

proposals

Proposals for new features in Dapr
15
star
23

test-infra

Test apps and tools for Dapr
C#
14
star
24

setup-dapr

GitHub Action for installing the Dapr CLI
JavaScript
10
star
25

docs-zh

Chinese translation of the Dapr documentation
9
star
26

kubernetes-operator

Go
6
star
27

blog

HTML
5
star
28

website

Website for the Dapr project
HTML
5
star
29

sig-sdk-spec

Repository for Dapr SDk Spec Special Interest Group
3
star
30

.github

1
star
31

homebrew-tap

Repository to enable Dapr cli installation via macOS' Homebrew.
Ruby
1
star