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

cleans up all the readmes (#66) 

* cleans up all the readmes

* fixed review comments
This commit is contained in:
Mark Chmarny 2020-09-17 18:17:26 -07:00 committed by GitHub
parent be62af92a7
commit fb1acd943f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 106 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
CONTRIBUTING.md
View File

@ -2,23 +2,17 @@
Thank you for your interest in Dapr go SDK!
This project welcomes contributions and suggestions. Most contributions require you to
agree to a Contributor License Agreement (CLA) declaring that you have the right to,
and actually do, grant us the rights to use your contribution.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution.
For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need
to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the
instructions provided by the bot. You will only need to do this once across all repositories using our CLA.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct.
For more information see the Code of Conduct FAQ
or contact opencode@microsoft.com with any additional questions or comments.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Contributions come in many forms: submitting issues, writing code, participating in discussions and community calls.
This document provides the guidelines for how to contribute to the Dapr project.
This document provides the guidelines for how to contribute to the Dapr go SDK project.
## Issues
@ -46,9 +40,9 @@ Before you file an issue, make sure you've checked the following:
- Some changes to the Dapr go SDK may require changes to the API. In that case, the best place to discuss the potential feature is the main [Dapr repo](https://github.com/dapr/dapr).
- Other examples could include bindings, state stores or entirely new components.
## Contributing to Dapr
## Contributing to Dapr go SDK
This section describes the guidelines for contributing code / docs to Dapr.
This section describes the guidelines for contributing code/docs to Dapr go SDK.
### Pull Requests
@ -70,7 +64,7 @@ A good way to communicate before investing too much time is to create a "Work-in
### Use of Third-party code
- All third-party code must be placed in the `vendor/` folder.
- `vendor/` folder is managed by Go modules and stores the source code of third-party Go dependencies. - The `vendor/` folder should not be modified manually.
- `vendor/` folder is managed by go modules which stores the source code of third-party go dependencies. - The `vendor/` folder should not be modified manually.
- Third-party code must include licenses.
A non-exclusive list of code that must be places in `vendor/`:

23
Readme.md
View File

@ -1,6 +1,6 @@
# Dapr SDK for Go
Client library to accelerate Dapr application development in go. This client supports all public [Dapr API](https://github.com/dapr/docs/tree/master/reference/api) and focuses on developer productivity.
Client library to help you build Dapr application in go. This client supports all public [Dapr APIs](https://github.com/dapr/docs/tree/master/reference/api) while focusing on idiomatic go experience and developer productivity.
[![Test](https://github.com/dapr/go-sdk/workflows/Test/badge.svg)](https://github.com/dapr/go-sdk/actions?query=workflow%3ATest) [![Release](https://github.com/dapr/go-sdk/workflows/Release/badge.svg)](https://github.com/dapr/go-sdk/actions?query=workflow%3ARelease) [![Go Report Card](https://goreportcard.com/badge/github.com/dapr/go-sdk)](https://goreportcard.com/report/github.com/dapr/go-sdk) ![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/dapr/go-sdk)
@ -8,9 +8,9 @@ Client library to accelerate Dapr application development in go. This client sup
> Assuming you already have [installed](https://golang.org/doc/install) go
Dapr go client includes two packages: `client` (for invoking public Dapr API) and `service` (to create services in go that can be invoked by Dapr, this is sometimes refereed to as "callback").
Dapr go client includes two packages: `client` (for invoking public Dapr API), and `service` (to create services that will be invoked by Dapr, this is sometimes refereed to as "callback").
### Client
### Creating client
Import Dapr go `client` package:
@ -37,7 +37,7 @@ func main() {
}
```
Assuming you have [Dapr CLI](https://github.com/dapr/docs/blob/master/getting-started/environment-setup.md) installed locally, you can then launch your app locally like this:
Assuming you have [Dapr CLI](https://github.com/dapr/docs/blob/master/getting-started/environment-setup.md) installed, you can then launch your app locally like this:
```shell
dapr run --app-id example-service \
@ -46,17 +46,16 @@ dapr run --app-id example-service \
go run main.go
```
Check the [example folder](./example) for working Dapr go client examples.
See the [example folder](./example) for more working Dapr client examples.
#### Usage
The Dapr go client supports following functionality:
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 methods for `Save`, `Get`, and `Delete`:
For simple use-cases, Dapr client provides easy to use `Save`, `Get`, and `Delete` methods:
```go
ctx := context.Background()
@ -81,7 +80,7 @@ if err := client.DeleteState(ctx, store, "key1"); err != nil {
}
```
For more granular control, the Dapr go client exposed `SetStateItem` type which can be use to gain more control over the state operations and allow for multiple items to be saved at once:
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{
@ -123,7 +122,7 @@ keys := []string{"key1", "key2", "key3"}
items, err := client.GetBulkItems(ctx, store, keys, 100)
```
And the `ExecuteStateTransaction` method to transactionally execute multiple `upsert` or `delete` operations.
And the `ExecuteStateTransaction` method to execute multiple `upsert` or `delete` operations transactionally.
```go
ops := make([]*dapr.StateOperation, 0)
@ -148,7 +147,7 @@ err := testClient.ExecuteStateTransaction(ctx, store, meta, ops)
##### PubSub
To publish data onto a topic the Dapr client provides a simple method:
To publish data onto a topic, the Dapr client provides a simple method:
```go
data := []byte(`{ "id": "a123", "value": "abcdefg", "valid": true }`)
@ -238,7 +237,7 @@ func main() {
## Service (callback)
In addition to this Dapr API client, Dapr go SDK also provides `service` package to bootstrap your Dapr callback services in either gRPC or HTTP. Instructions on how to use it are located [here](./service/Readme.md)
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](./service/Readme.md)
## Contributing to Dapr go client

4
service/Readme.md
View File

@ -1,13 +1,13 @@
# 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 in either gRPC or HTTP:
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](./http/Readme.md)
* [gRPC Service](./grpc/Readme.md)
## Templates
To accelerate your Dapr app development in go even further you can use one of the GitHub templates integrating these Dapr callback packages:
To accelerate your Dapr app development in go even further, we've craated a few GitHub templates which build on the above Dapr callback packages:
* [Dapr gRPC Service in Go](https://github.com/mchmarny/dapr-grpc-service-template) - Template project to jump start your Dapr event subscriber service with gRPC development
* [Dapr HTTP Event Subscriber in Go](https://github.com/mchmarny/dapr-http-event-subscriber-template) - Template project to jump start your Dapr event subscriber service with HTTP development

76
service/grpc/Readme.md
View File

@ -6,57 +6,75 @@ Start by importing Dapr go `service/grpc` package:
daprd "github.com/dapr/go-sdk/service/grpc"
```
## Event Handling
## Creating and Starting Service
To handle events from specific topic, first create a Dapr service, add topic event handler, and start the 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)
}
```
if err := s.AddTopicEventHandler("messages", "topic1", eventHandler); err != nil {
log.Fatalf("error adding topic subscription: %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, err := daprd.NewService(list)
if err != nil {
log.Fatalf("failed to start the server: %v", err)
}
```
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
if err := s.AddTopicEventHandler("messages", "topic1", 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 *daprd.TopicEvent) 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 nil
}
```
## Service Invocation Handler
To handle service invocations, create and start the Dapr service as in the above example. In this case though add the handler for service invocation:
To handle service invocations you will need to add at least one service invocation handler before starting the service:
```go
s, err := daprd.NewService(":50001")
if err != nil {
log.Fatalf("failed to start the server: %v", err)
}
if err := s.AddServiceInvocationHandler("echo", echoHandler); err != nil {
log.Fatalf("error adding invocation handler: %v", err)
}
```
if err := s.Start(); err != nil {
log.Fatalf("server error: %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) {
if in == nil {
err = errors.New("invocation parameter required")
return
}
log.Printf(
"echo - ContentType:%s, Verb:%s, QueryString:%s, %+v",
in.ContentType, in.Verb, in.QueryString, string(in.Data),
)
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,
@ -68,31 +86,27 @@ func echoHandler(ctx context.Context, in *common.InvocationEvent) (out *common.C
## Binding Invocation Handler
To handle binding invocations, create and start the Dapr service as in the above examples. In this case though add the handler for binding invocation:
To handle binding invocations you will need to add at least one binding invocation handler before starting the service:
```go
s, err := daprd.NewService(":50001")
if err != nil {
log.Fatalf("failed to start the server: %v", err)
}
if err := s.AddBindingInvocationHandler("run", runHandler); err != nil {
log.Fatalf("error adding binding handler: %v", err)
}
```
if err := s.Start(); err != nil {
log.Fatalf("server error: %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
}
```
## Templates
To accelerate your Dapr app development in go even further you can use one of the GitHub templates integrating the gRPC Dapr callback package:
To accelerate your gRPC Dapr app development in go even further you can use one of the GitHub templates integrating the gRPC Dapr callback package:
* [Dapr gRPC Service in Go](https://github.com/mchmarny/dapr-grpc-service-template) - Template project to jump start your Dapr event subscriber service with gRPC development
* [Dapr gRPC Event Subscriber in Go](https://github.com/mchmarny/dapr-grpc-event-subscriber-template) - Template project to jump start your Dapr event subscriber service with gRPC development

64
service/http/Readme.md
View File

@ -6,13 +6,35 @@ Start by importing Dapr go `service/http` package:
daprd "github.com/dapr/go-sdk/service/http"
```
## Event Handling
## Creating and Starting Service
To handle events from specific topic, first create a Dapr service, add topic event handler, and start the 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.NewService(":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",
@ -22,41 +44,34 @@ err := s.AddTopicEventHandler(sub, eventHandler)
if err != nil {
log.Fatalf("error adding topic subscription: %v", err)
}
```
if err = s.Start(); err != nil && err != http.ErrServerClosed {
log.Fatalf("error listening: %v", err)
}
The handler method itself can be any method with the expected signature:
```go
func eventHandler(ctx context.Context, e *common.TopicEvent) 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 nil
}
```
## Service Invocation Handler
To handle service invocations, create and start the Dapr service as in the above example. In this case though add the handler for service invocation:
To handle service invocations you will need to add at least one service invocation handler before starting the service:
```go
s := daprd.NewService(":8080")
if err := s.AddServiceInvocationHandler("/echo", echoHandler); err != nil {
log.Fatalf("error adding invocation handler: %v", err)
}
```
if err := s.Start(); err != nil {
log.Fatalf("server error: %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) {
if in == nil {
err = errors.New("invocation parameter required")
return
}
log.Printf(
"echo - ContentType:%s, Verb:%s, QueryString:%s, %+v",
in.ContentType, in.Verb, in.QueryString, string(in.Data),
)
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,
@ -68,24 +83,27 @@ func echoHandler(ctx context.Context, in *common.InvocationEvent) (out *common.C
## Binding Invocation Handler
To handle binding invocations, create and start the Dapr service as in the above examples. In this case though add the handler for binding invocation:
To handle binding invocations you will need to add at least one binding invocation handler before starting the service:
```go
s := daprd.NewService(":8080")
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
}
```
## Templates
To accelerate your Dapr app development in go even further you can use one of the GitHub templates integrating the HTTP Dapr callback package:
To accelerate your HTTP Dapr app development in go even further you can use one of the GitHub templates integrating the HTTP Dapr callback package:
* [Dapr HTTP Event Subscriber in Go](https://github.com/mchmarny/dapr-http-event-subscriber-template) - Template project to jump start your Dapr event subscriber service with HTTP development
* [Dapr HTTP cron Handler in Go](https://github.com/mchmarny/dapr-http-cron-handler-template) - Template project to jump start your Dapr service development for scheduled workloads