dapr
/
go-sdk
mirror of https://github.com/dapr/go-sdk.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add Dapr Docs for Go SDK (#182) 

* Add Dapr Docs for Go SDK

* Fix section titles

* Update grpc-service.md

* Update cards links
This commit is contained in:
greenie-msft 2021-07-01 11:40:22 -07:00 committed by GitHub
parent 4122595b0e
commit a9c6bcb4f4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 523 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
daprdocs/README.md Normal file
View File

@ -0,0 +1,25 @@
# Dapr Go SDK documentation
This page covers how the documentation is structured for the Dapr Go SDK
## Dapr Docs
All Dapr documentation is hosted at [docs.dapr.io](https://docs.dapr.io), including the docs for the [Go SDK](https://docs.dapr.io/developing-applications/sdks/go/). Head over there if you want to read the docs.
### Go SDK docs source
Although the docs site code and content is in the [docs repo](https://github.com/dapr/docs), the Go SDK content and images are within the `content` and `static` directories, respectively.
This allows separation of roles and expertise between maintainers, and makes it easy to find the docs files you are looking for.
## Writing Go SDK docs
To get up and running to write Go SDK docs, visit the [docs repo](https://github.com/dapr/docs) to initialize your environment. It will clone both the docs repo and this repo, so you can make changes and see it rendered within the site instantly, as well as commit and PR into this repo.
Make sure to read the [docs contributing guide](https://docs.dapr.io/contributing/contributing-docs/) for information on style/semantics/etc.
## Docs architecture
The docs site is built on [Hugo](https://gohugo.io), which lives in the docs repo. This repo is setup as a git submodule so that when the repo is cloned and initialized, the dotnet-sdk repo, along with the docs, are cloned as well.
Then, in the Hugo configuration file, the `daprdocs/content` and `daprdocs/static` directories are redirected to the `daprdocs/developing-applications/sdks/go` and `static/go` directories, respectively. Thus, all the content within this repo is folded into the main docs site.

23
daprdocs/content/en/go-sdk-contributing/go-contributing.md Normal file
View File

@ -0,0 +1,23 @@
---
type: docs
title: "Contributing to the Go SDK"
linkTitle: "Go SDK"
weight: 3000
description: Guidelines for contributing to the Dapr Go SDK
---
When contributing to the [Go SDK](https://github.com/dapr/go-sdk) the following rules and best-practices should be followed.
## Examples
The `examples` directory contains code samples for users to run to try out specific functionality of the various Go SDK packages and extensions. When writing new and updated samples keep in mind:
- All examples should be runnable on Windows, Linux, and MacOS. While Go code is consistent among operating systems, any pre/post example commands should provide options through [codetabs]({{< ref "contributing-docs.md#tabbed-content" >}})
- Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be able to start on the example and complete it without an error. Links to external download pages are fine.
## Docs
The `daprdocs` directory contains the markdown files that are rendered into the [Dapr Docs](https://docs.dapr.io) website. When the documentation website is built this repo is cloned and configured so that its contents are rendered with the docs content. When writing docs keep in mind:
- All rules in the [docs guide]({{< ref contributing-docs.md >}}) should be followed in addition to these.
- All files and directories should be prefixed with `go-` to ensure all file/directory names are globally unique across all Dapr documentation.

23
daprdocs/content/en/go-sdk-docs/_index.md Normal file
View File

@ -0,0 +1,23 @@
---
type: docs
title: "Dapr Go SDK"
linkTitle: "Go"
weight: 1000
description: Go SDK packages for developing Dapr applications
no_list: true
---
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.
{{< cardpane >}}
{{< card title="**Client**">}}
Use the Go Client SDK for invoking public Dapr APIs
[**Learn more about the Go Client SDK**]({{< ref go-client >}})
{{< /card >}}
{{< card title="**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**]({{< ref go-service >}})
{{< /card >}}
{{< /cardpane >}}

219
daprdocs/content/en/go-sdk-docs/go-client/_index.md Normal file
View File

@ -0,0 +1,219 @@
---
type: docs
title: "Getting started with the Dapr client Go SDK"
linkTitle: "Client"
weight: 20000
description: How to get up and running with the Dapr Go SDK
no_list: true
---
The Dapr client package allows you to interact with other Dapr applications from a Go application.
## Prerequisites
- [Dapr CLI]({{< ref install-dapr-cli.md >}}) installed
- Initialized [Dapr environment]({{< ref install-dapr-selfhost.md >}})
- [Go installed](https://golang.org/doc/install)
## Import the client package
```go
import "github.com/dapr/go-sdk/client"
```
## Building blocks
The Go SDK allows you to interface with all of the [Dapr building blocks]({{< ref 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:
```go
resp, err := client.InvokeMethod(ctx, "app-id", "method-name", "post")
```
Invoke a service with data:
```go
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]({{< ref howto-invoke-discover-services.md >}}).
### State Management
For simple use-cases, Dapr client provides easy to use `Save`, `Get`, `Delete` methods:
```go
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); err != nil {
panic(err)
}
// get state for key key1
item, err := client.GetState(ctx, store, "key1")
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"); 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:
```go
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:
```go
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.
```go
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)
```
### Publish Messages
To publish data onto a topic, the Dapr Go client provides a simple method:
```go
data := []byte(`{ "id": "a123", "value": "abcdefg", "valid": true }`)
if err := client.PublishEvent(ctx, "component-name", "topic-name", data); err != nil {
panic(err)
}
```
- For a full list of state operations visit [How-To: Publish & subscribe]({{< ref howto-publish-subscribe.md >}}).
### 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 biding:
```go
in := &dapr.InvokeBindingRequest{ Name: "binding-name", Operation: "operation-name" }
err = client.InvokeOutputBinding(ctx, in)
```
To invoke method with content and metadata:
```go
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]({{< ref howto-bindings.md >}}).
### 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):
```go
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.
```go
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]({{< ref howto-secrets.md >}}).
## Related links
- [Go SDK Examples](https://github.com/dapr/go-sdk/tree/main/examples)

11
daprdocs/content/en/go-sdk-docs/go-server/_index.md Normal file
View File

@ -0,0 +1,11 @@
---
type: docs
title: "Getting started with the Dapr Service (Callback) SDK for Go"
linkTitle: "Service"
weight: 20000
description: How to get up and running with the Dapr Service (Callback) SDK for Go
no_list: true
---
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:
- [HTTP Service]({{< ref http-service.md >}})
- [gRPC Service]({{< ref grpc-service.md >}})

114
daprdocs/content/en/go-sdk-docs/go-server/grpc-service.md Normal file
View File

@ -0,0 +1,114 @@
---
type: docs
title: "Getting started with the Dapr Service (Callback) SDK for Go"
linkTitle: "gRPC Service"
weight: 20000
description: How to get up and running with the Dapr Service (Callback) SDK for Go
no_list: true
---
## Dapr gRPC Service SDK for Go
### Prerequisite
Start by importing Dapr Go service/grpc package:
```go
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:
```go
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:
```go
list, err := net.Listen("tcp", "localhost:0")
if err != nil {
log.Fatalf("gRPC listener creation failed: %s", err)
}
s := daprd.NewServiceWithListener(list)
```
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:
```go
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:
```go
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:
```go
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
}
```
### Service Invocation Handler
To handle service invocations you will need to add at least one service invocation handler before starting the service:
```go
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:
```go
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:
```go
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:
```go
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
}
```
## Related links
- [Go SDK Examples](https://github.com/dapr/go-sdk/tree/main/examples)

108
daprdocs/content/en/go-sdk-docs/go-server/http-service.md Normal file
View File

@ -0,0 +1,108 @@
---
type: docs
title: "Getting started with the Dapr HTTP Service SDK for Go"
linkTitle: "HTTP Service"
weight: 10000
description: How to get up and running with the Dapr HTTP Service SDK for Go
no_list: true
---
### Prerequisite
Start by importing Dapr Go service/http package:
```go
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:
```go
s := daprd.NewService(":8080")
```
Or with address and an existing http.ServeMux in case you want to combine existing server implementations:
```go
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:
```go
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:
```go
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:
```go
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
}
```
### Service Invocation Handler
To handle service invocations you will need to add at least one service invocation handler before starting the service:
```go
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:
```go
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
```go
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:
```go
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
}
```
## Related links
- [Go SDK Examples](https://github.com/dapr/go-sdk/tree/main/examples)