From 235bf6d577e2e83d2ac2bb1584e9115aae67755a Mon Sep 17 00:00:00 2001 From: Marc Duiker Date: Fri, 21 Nov 2025 13:16:17 +0000 Subject: [PATCH 1/3] Remove Go SDK submodule Signed-off-by: Marc Duiker --- .gitmodules | 3 --- sdkdocs/go | 1 - 2 files changed, 4 deletions(-) delete mode 160000 sdkdocs/go diff --git a/.gitmodules b/.gitmodules index cb2249af216..74b8854259e 100644 --- a/.gitmodules +++ b/.gitmodules @@ -8,9 +8,6 @@ path = translations/docs-zh url = https://github.com/dapr/docs-zh.git branch = v1.0_content -[submodule "sdkdocs/go"] - path = sdkdocs/go - url = https://github.com/dapr/go-sdk.git [submodule "sdkdocs/java"] path = sdkdocs/java url = https://github.com/dapr/java-sdk.git diff --git a/sdkdocs/go b/sdkdocs/go deleted file mode 160000 index 6dd434913b6..00000000000 --- a/sdkdocs/go +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 6dd434913b6fb41f6ede006c64c01a35a02c458f From a193f2fed8429ff5da7700ff8788277bf8721ab4 Mon Sep 17 00:00:00 2001 From: Marc Duiker Date: Fri, 21 Nov 2025 13:17:33 +0000 Subject: [PATCH 2/3] Remove Go Pluggable Component submodule Signed-off-by: Marc Duiker --- .gitmodules | 3 --- sdkdocs/pluggable-components/go | 1 - 2 files changed, 4 deletions(-) delete mode 160000 sdkdocs/pluggable-components/go diff --git a/.gitmodules b/.gitmodules index 74b8854259e..5d73904cfad 100644 --- a/.gitmodules +++ b/.gitmodules @@ -14,9 +14,6 @@ [submodule "sdkdocs/js"] path = sdkdocs/js url = https://github.com/dapr/js-sdk.git -[submodule "sdkdocs/pluggable-components/go"] - path = sdkdocs/pluggable-components/go - url = https://github.com/dapr-sandbox/components-go-sdk [submodule "sdkdocs/rust"] path = sdkdocs/rust url = https://github.com/dapr/rust-sdk.git diff --git a/sdkdocs/pluggable-components/go b/sdkdocs/pluggable-components/go deleted file mode 160000 index 25b080a8e8d..00000000000 --- a/sdkdocs/pluggable-components/go +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 25b080a8e8d1d897f32ee2ce31e617f89f972e32 From f33f14b794faa55bc23899ccbed8ba855e900524 Mon Sep 17 00:00:00 2001 From: Marc Duiker Date: Fri, 21 Nov 2025 13:35:58 +0000 Subject: [PATCH 3/3] Add Go SDk & Pluggable component docs Signed-off-by: Marc Duiker --- hugo.yaml | 6 +- sdkdocs/go/README.md | 25 + .../en/go-sdk-contributing/go-contributing.md | 23 + sdkdocs/go/content/en/go-sdk-docs/_index.md | 28 + .../en/go-sdk-docs/go-client/_index.md | 704 ++++++++++++++++++ .../en/go-sdk-docs/go-service/_index.md | 11 + .../en/go-sdk-docs/go-service/grpc-service.md | 159 ++++ .../en/go-sdk-docs/go-service/http-service.md | 153 ++++ .../go/content/en/go-sdk-docs/_index.md | 174 +++++ .../en/go-sdk-docs/go-advanced/_index.md | 76 ++ .../en/go-sdk-docs/go-bindings/_index.md | 131 ++++ .../en/go-sdk-docs/go-pub-sub/_index.md | 113 +++ .../en/go-sdk-docs/go-state-store/_index.md | 147 ++++ 13 files changed, 1747 insertions(+), 3 deletions(-) create mode 100644 sdkdocs/go/README.md create mode 100644 sdkdocs/go/content/en/go-sdk-contributing/go-contributing.md create mode 100644 sdkdocs/go/content/en/go-sdk-docs/_index.md create mode 100644 sdkdocs/go/content/en/go-sdk-docs/go-client/_index.md create mode 100644 sdkdocs/go/content/en/go-sdk-docs/go-service/_index.md create mode 100644 sdkdocs/go/content/en/go-sdk-docs/go-service/grpc-service.md create mode 100644 sdkdocs/go/content/en/go-sdk-docs/go-service/http-service.md create mode 100644 sdkdocs/pluggable-components/go/content/en/go-sdk-docs/_index.md create mode 100644 sdkdocs/pluggable-components/go/content/en/go-sdk-docs/go-advanced/_index.md create mode 100644 sdkdocs/pluggable-components/go/content/en/go-sdk-docs/go-bindings/_index.md create mode 100644 sdkdocs/pluggable-components/go/content/en/go-sdk-docs/go-pub-sub/_index.md create mode 100644 sdkdocs/pluggable-components/go/content/en/go-sdk-docs/go-state-store/_index.md diff --git a/hugo.yaml b/hugo.yaml index 31b591c9817..0c92a1da2ce 100644 --- a/hugo.yaml +++ b/hugo.yaml @@ -290,10 +290,10 @@ module: - source: sdkdocs/dotnet/content/en/dotnet-sdk-contributing target: content/contributing/sdk-contrib/ lang: en - - source: sdkdocs/go/daprdocs/content/en/go-sdk-docs + - source: sdkdocs/go/content/en/go-sdk-docs target: content/developing-applications/sdks/go lang: en - - source: sdkdocs/go/daprdocs/content/en/go-sdk-contributing + - source: sdkdocs/go/content/en/go-sdk-contributing target: content/contributing/sdk-contrib/ lang: en - source: sdkdocs/java/daprdocs/content/en/java-sdk-docs @@ -317,7 +317,7 @@ module: - source: sdkdocs/pluggable-components/dotnet/content/en/dotnet-sdk-docs target: content/developing-applications/develop-components/pluggable-components/pluggable-components-sdks/pluggable-components-dotnet lang: en - - source: sdkdocs/pluggable-components/go/daprdocs/content/en/go-sdk-docs + - source: sdkdocs/pluggable-components/go/content/en/go-sdk-docs target: content/developing-applications/develop-components/pluggable-components/pluggable-components-sdks/pluggable-components-go lang: en - source: translations/docs-zh/translated_content/zh_CN/docs diff --git a/sdkdocs/go/README.md b/sdkdocs/go/README.md new file mode 100644 index 00000000000..0e0ec048c7e --- /dev/null +++ b/sdkdocs/go/README.md @@ -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. \ No newline at end of file diff --git a/sdkdocs/go/content/en/go-sdk-contributing/go-contributing.md b/sdkdocs/go/content/en/go-sdk-contributing/go-contributing.md new file mode 100644 index 00000000000..ae15e89ad78 --- /dev/null +++ b/sdkdocs/go/content/en/go-sdk-contributing/go-contributing.md @@ -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 [tabpane]({{% 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. diff --git a/sdkdocs/go/content/en/go-sdk-docs/_index.md b/sdkdocs/go/content/en/go-sdk-docs/_index.md new file mode 100644 index 00000000000..49327b5a6e6 --- /dev/null +++ b/sdkdocs/go/content/en/go-sdk-docs/_index.md @@ -0,0 +1,28 @@ +--- +type: docs +title: "Dapr Go SDK" +linkTitle: "Go" +weight: 1000 +description: Go SDK packages for developing Dapr applications +no_list: true +cascade: + github_repo: https://github.com/dapr/go-sdk + github_subdir: daprdocs/content/en/go-sdk-docs + path_base_for_github_subdir: content/en/developing-applications/sdks/go/ + github_branch: main +--- + +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 %}} \ No newline at end of file diff --git a/sdkdocs/go/content/en/go-sdk-docs/go-client/_index.md b/sdkdocs/go/content/en/go-sdk-docs/go-client/_index.md new file mode 100644 index 00000000000..3cb76db194e --- /dev/null +++ b/sdkdocs/go/content/en/go-sdk-docs/go-client/_index.md @@ -0,0 +1,704 @@ +--- +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" +``` +## Error handling +Dapr errors are based on [gRPC's richer error model](https://cloud.google.com/apis/design/errors#error_model). +The following code shows an example of how you can parse and handle the error details: + +```go +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) + } + } +} +``` + +## 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 %}}). + +### Workflows + +Workflows and their activities can be authored and managed using the Dapr Go SDK like so: + +```go +import ( +... +"github.com/dapr/go-sdk/workflow" +... +) + +func ExampleWorkflow(ctx *workflow.WorkflowContext) (any, error) { + var output string + input := "world" + + if err := ctx.CallActivity(ExampleActivity, workflow.ActivityInput(input)).Await(&output); err != nil { + return nil, err + } + + // Print output - "hello world" + fmt.Println(output) + + return nil, nil +} + +func ExampleActivity(ctx workflow.ActivityContext) (any, error) { + var input int + if err := ctx.GetInput(&input); err != nil { + return "", err + } + + return fmt.Sprintf("hello %s", input), nil +} + +func main() { + // Create a workflow worker + w, err := workflow.NewWorker() + if err != nil { + log.Fatalf("error creating worker: %v", err) + } + + // Register the workflow + w.RegisterWorkflow(ExampleWorkflow) + + // Register the activity + w.RegisterActivity(ExampleActivity) + + // Start workflow runner + if err := w.Start(); err != nil { + log.Fatal(err) + } + + // Create a workflow client + wfClient, err := workflow.NewClient() + if err != nil { + log.Fatal(err) + } + + // Start a new workflow + id, err := wfClient.ScheduleNewWorkflow(context.Background(), "ExampleWorkflow") + if err != nil { + log.Fatal(err) + } + + // Wait for the workflow to complete + metadata, err := wfClient.WaitForWorkflowCompletion(ctx, id) + if err != nil { + log.Fatal(err) + } + + // Print workflow status post-completion + fmt.Println(metadata.RuntimeStatus) + + // Shutdown Worker + w.Shutdown() +} +``` + +- For a more comprehensive guide on workflows visit these How-To guides: + - [How-To: Author a workflow]({{% ref howto-author-workflow.md %}}). + - [How-To: Manage a workflow]({{% ref howto-manage-workflow.md %}}). +- Visit the Go SDK Examples to jump into complete examples: + - [Workflow Example](https://github.com/dapr/go-sdk/tree/main/examples/workflow) + - [Workflow - Parallelised](https://github.com/dapr/go-sdk/tree/main/examples/workflow-parallel) + +### 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, 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 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) +``` + +Retrieve, filter, and sort key/value data stored in your statestore using `QueryState`. + +```go +// Define the query string +query := `{ + "filter": { + "EQ": { "value.Id": "1" } + }, + "sort": [ + { + "key": "value.Balance", + "order": "DESC" + } + ] +}` + +// Use the client to query the state +queryResponse, err := c.QueryState(ctx, "querystore", query) +if err != nil { + log.Fatal(err) +} + +fmt.Printf("Got %d\n", len(queryResponse)) + +for _, account := range queryResponse { + var data Account + err := account.Unmarshal(&data) + if err != nil { + log.Fatal(err) + } + + fmt.Printf("Account: %s has %f\n", data.ID, data.Balance) +} +``` + +> **Note:** Query state API is currently in alpha + +For a full guide on state management, visit [How-To: Save & get state]({{% ref howto-get-save-state.md %}}). + +### 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) +} +``` + +To publish multiple messages at once, the `PublishEvents` method can be used: + +```go +events := []string{"event1", "event2", "event3"} +res := client.PublishEvents(ctx, "component-name", "topic-name", events) +if res.Error != nil { + panic(res.Error) +} +``` + +For a full guide on pub/sub, visit [How-To: Publish & subscribe]({{% ref howto-publish-subscribe.md %}}). + +### Workflow + +You can create [workflows]({{% ref workflow-overview.md %}}) using the Go SDK. For example, start with a simple workflow activity: + +```go +func TestActivity(ctx workflow.ActivityContext) (any, error) { + var input int + if err := ctx.GetInput(&input); err != nil { + return "", err + } + + // Do something here + return "result", nil +} +``` + +Write a simple workflow function: + +```go +func TestWorkflow(ctx *workflow.WorkflowContext) (any, error) { + var input int + if err := ctx.GetInput(&input); err != nil { + return nil, err + } + var output string + if err := ctx.CallActivity(TestActivity, workflow.ActivityInput(input)).Await(&output); err != nil { + return nil, err + } + if err := ctx.WaitForExternalEvent("testEvent", time.Second*60).Await(&output); err != nil { + return nil, err + } + + if err := ctx.CreateTimer(time.Second).Await(nil); err != nil { + return nil, nil + } + return output, nil +} +``` + +Then compose your application that will use the workflow you've created. [Refer to the How-To: Author workflows guide]({{% ref howto-author-workflow.md %}}) for a full walk-through. + +Try out the [Go SDK workflow example.](https://github.com/dapr/go-sdk/blob/main/examples/workflow) + +### Jobs + +The Dapr client Go SDK allows you to schedule, get, and delete jobs. Jobs enable you to schedule work to be executed at specific times or intervals. + +#### Scheduling a Job + +To schedule a new job, use the `ScheduleJobAlpha1` method: + +```go +import ( + "google.golang.org/protobuf/types/known/anypb" +) + +// Create job data +data, err := anypb.New(&YourDataStruct{Message: "Hello, Job!"}) +if err != nil { + panic(err) +} + +// Create a simple job using the builder pattern +job := client.NewJob("my-scheduled-job", + client.WithJobData(data), + client.WithJobDueTime("10s"), // Execute in 10 seconds +) + +// Schedule the job +err = client.ScheduleJobAlpha1(ctx, job) +if err != nil { + panic(err) +} +``` + +#### Job with Schedule and Repeats + +You can create recurring jobs using the `Schedule` field with cron expressions: + +```go +job := client.NewJob("recurring-job", + client.WithJobData(data), + client.WithJobSchedule("0 9 * * *"), // Run at 9 AM every day + client.WithJobRepeats(10), // Repeat 10 times + client.WithJobTTL("1h"), // Job expires after 1 hour +) + +err = client.ScheduleJobAlpha1(ctx, job) +``` + +#### Job with Failure Policy + +Configure how jobs should handle failures using failure policies: + +```go +// Constant retry policy with max retries and interval +job := client.NewJob("resilient-job", + client.WithJobData(data), + client.WithJobDueTime("2024-01-01T10:00:00Z"), + client.WithJobConstantFailurePolicy(), + client.WithJobConstantFailurePolicyMaxRetries(3), + client.WithJobConstantFailurePolicyInterval(30*time.Second), +) + +err = client.ScheduleJobAlpha1(ctx, job) +``` + +For jobs that should not be retried on failure, use the drop policy: + +```go +job := client.NewJob("one-shot-job", + client.WithJobData(data), + client.WithJobDueTime("2024-01-01T10:00:00Z"), + client.WithJobDropFailurePolicy(), +) + +err = client.ScheduleJobAlpha1(ctx, job) +``` + +#### Getting a Job + +To get information about a scheduled job: + +```go +job, err := client.GetJobAlpha1(ctx, "my-scheduled-job") +if err != nil { + panic(err) +} + +fmt.Printf("Job: %s, Schedule: %s, Repeats: %d\n", + job.Name, job.Schedule, job.Repeats) +``` + +#### Deleting a Job + +To cancel a scheduled job: + +```go +err = client.DeleteJobAlpha1(ctx, "my-scheduled-job") +if err != nil { + panic(err) +} +``` + +For a full guide on jobs, visit [How-To: Schedule and manage jobs]({{< ref howto-schedule-and-handle-triggered-jobs.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 binding: + +```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 %}}). + +### Actors + +Use the Dapr Go client SDK to write actors. + +```go +// MyActor represents an example actor type. +type MyActor struct { + actors.Actor +} + +// MyActorMethod is a method that can be invoked on MyActor. +func (a *MyActor) MyActorMethod(ctx context.Context, req *actors.Message) (string, error) { + log.Printf("Received message: %s", req.Data) + return "Hello from MyActor!", nil +} + +func main() { + // Create a Dapr client + daprClient, err := client.NewClient() + if err != nil { + log.Fatal("Error creating Dapr client: ", err) + } + + // Register the actor type with Dapr + actors.RegisterActor(&MyActor{}) + + // Create an actor client + actorClient := actors.NewClient(daprClient) + + // Create an actor ID + actorID := actors.NewActorID("myactor") + + // Get or create the actor + err = actorClient.SaveActorState(context.Background(), "myactorstore", actorID, map[string]interface{}{"data": "initial state"}) + if err != nil { + log.Fatal("Error saving actor state: ", err) + } + + // Invoke a method on the actor + resp, err := actorClient.InvokeActorMethod(context.Background(), "myactorstore", actorID, "MyActorMethod", &actors.Message{Data: []byte("Hello from client!")}) + if err != nil { + log.Fatal("Error invoking actor method: ", err) + } + + log.Printf("Response from actor: %s", resp.Data) + + // Wait for a few seconds before terminating + time.Sleep(5 * time.Second) + + // Delete the actor + err = actorClient.DeleteActor(context.Background(), "myactorstore", actorID) + if err != nil { + log.Fatal("Error deleting actor: ", err) + } + + // Close the Dapr client + daprClient.Close() +} +``` + +For a full guide on actors, visit [the Actors building block documentation]({{% ref actors %}}). + +### 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 %}}). + +### Distributed Lock + +The Dapr client provides mutually exclusive access to a resource using a lock. With a lock, you can: + +- Provide access to a database row, table, or an entire database +- Lock reading messages from a queue in a sequential manner + +```go +package main + +import ( + "fmt" + + dapr "github.com/dapr/go-sdk/client" +) + +func main() { + client, err := dapr.NewClient() + if err != nil { + panic(err) + } + defer client.Close() + + resp, err := client.TryLockAlpha1(ctx, "lockstore", &dapr.LockRequest{ + LockOwner: "random_id_abc123", + ResourceID: "my_file_name", + ExpiryInSeconds: 60, + }) + + fmt.Println(resp.Success) +} +``` + +For a full guide on distributed lock, visit [How-To: Use a lock]({{% ref howto-use-distributed-lock.md %}}). + +### Configuration + +With the Dapr client Go SDK, you can consume configuration items that are returned as read-only key/value pairs, and subscribe to configuration item changes. + +#### Config Get + +```go + items, err := client.GetConfigurationItem(ctx, "example-config", "mykey") + if err != nil { + panic(err) + } + fmt.Printf("get config = %s\n", (*items).Value) +``` + +#### Config Subscribe + +```go +go func() { + if err := client.SubscribeConfigurationItems(ctx, "example-config", []string{"mySubscribeKey1", "mySubscribeKey2", "mySubscribeKey3"}, func(id string, items map[string]*dapr.ConfigurationItem) { + for k, v := range items { + fmt.Printf("get updated config key = %s, value = %s \n", k, v.Value) + } + subscribeID = id + }); err != nil { + panic(err) + } +}() +``` + +For a full guide on configuration, visit [How-To: Manage configuration from a store]({{% ref howto-manage-configuration.md %}}). + +### Cryptography + +With the Dapr client Go SDK, you can use the high-level `Encrypt` and `Decrypt` cryptography APIs to encrypt and decrypt files while working on a stream of data. + +To encrypt: + +```go +// Encrypt the data using Dapr +out, err := client.Encrypt(context.Background(), rf, dapr.EncryptOptions{ + // These are the 3 required parameters + ComponentName: "mycryptocomponent", + KeyName: "mykey", + Algorithm: "RSA", +}) +if err != nil { + panic(err) +} +``` + +To decrypt: + +```go +// Decrypt the data using Dapr +out, err := client.Decrypt(context.Background(), rf, dapr.EncryptOptions{ + // Only required option is the component name + ComponentName: "mycryptocomponent", +}) +``` + +For a full guide on cryptography, visit [How-To: Use the cryptography APIs]({{% ref howto-cryptography.md %}}). + +## Related links +[Go SDK Examples](https://github.com/dapr/go-sdk/tree/main/examples) diff --git a/sdkdocs/go/content/en/go-sdk-docs/go-service/_index.md b/sdkdocs/go/content/en/go-sdk-docs/go-service/_index.md new file mode 100644 index 00000000000..93f51a9f884 --- /dev/null +++ b/sdkdocs/go/content/en/go-sdk-docs/go-service/_index.md @@ -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 %}}) \ No newline at end of file diff --git a/sdkdocs/go/content/en/go-sdk-docs/go-service/grpc-service.md b/sdkdocs/go/content/en/go-sdk-docs/go-service/grpc-service.md new file mode 100644 index 00000000000..33c7909d1c3 --- /dev/null +++ b/sdkdocs/go/content/en/go-sdk-docs/go-service/grpc-service.md @@ -0,0 +1,159 @@ +--- +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 +} +``` + +Optionally, you can use [routing rules](https://docs.dapr.io/developing-applications/building-blocks/pubsub/howto-route-messages/) to send messages to different handlers based on the contents of the CloudEvent. + +```go +sub := &common.Subscription{ + PubsubName: "messages", + Topic: "topic1", + Route: "/important", + Match: `event.type == "important"`, + Priority: 1, +} +err := s.AddTopicEventHandler(sub, importantHandler) +if err != nil { + log.Fatalf("error adding topic subscription: %v", err) +} +``` + +You can also create a custom type that implements the `TopicEventSubscriber` interface to handle your events: + +```go +type EventHandler struct { + // any data or references that your event handler needs. +} + +func (h *EventHandler) Handle(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 +} +``` + +The `EventHandler` can then be added using the `AddTopicEventSubscriber` method: + +```go +sub := &common.Subscription{ + PubsubName: "messages", + Topic: "topic1", +} +eventHandler := &EventHandler{ +// initialize any fields +} +if err := s.AddTopicEventSubscriber(sub, eventHandler); err != nil { + log.Fatalf("error adding topic subscription: %v", err) +} +``` + +### 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) diff --git a/sdkdocs/go/content/en/go-sdk-docs/go-service/http-service.md b/sdkdocs/go/content/en/go-sdk-docs/go-service/http-service.md new file mode 100644 index 00000000000..c73487e0650 --- /dev/null +++ b/sdkdocs/go/content/en/go-sdk-docs/go-service/http-service.md @@ -0,0 +1,153 @@ +--- +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 +} +``` + +Optionally, you can use [routing rules](https://docs.dapr.io/developing-applications/building-blocks/pubsub/howto-route-messages/) to send messages to different handlers based on the contents of the CloudEvent. + +```go +sub := &common.Subscription{ + PubsubName: "messages", + Topic: "topic1", + Route: "/important", + Match: `event.type == "important"`, + Priority: 1, +} +err := s.AddTopicEventHandler(sub, importantHandler) +if err != nil { + log.Fatalf("error adding topic subscription: %v", err) +} +``` + +You can also create a custom type that implements the `TopicEventSubscriber` interface to handle your events: + +```go +type EventHandler struct { + // any data or references that your event handler needs. +} + +func (h *EventHandler) Handle(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 +} +``` + +The `EventHandler` can then be added using the `AddTopicEventSubscriber` method: + +```go +sub := &common.Subscription{ + PubsubName: "messages", + Topic: "topic1", +} +eventHandler := &EventHandler{ +// initialize any fields +} +if err := s.AddTopicEventSubscriber(sub, eventHandler); err != nil { + log.Fatalf("error adding topic subscription: %v", err) +} +``` + +### 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) diff --git a/sdkdocs/pluggable-components/go/content/en/go-sdk-docs/_index.md b/sdkdocs/pluggable-components/go/content/en/go-sdk-docs/_index.md new file mode 100644 index 00000000000..e818629ffe9 --- /dev/null +++ b/sdkdocs/pluggable-components/go/content/en/go-sdk-docs/_index.md @@ -0,0 +1,174 @@ +--- +type: docs +title: "Getting started with the Dapr pluggable components Go SDK" +linkTitle: "Go" +weight: 1000 +description: How to get up and running with the Dapr pluggable components Go SDK +no_list: true +is_preview: true +cascade: + github_repo: https://github.com/dapr-sandbox/components-go-sdk + github_subdir: daprdocs/content/en/go-sdk-docs + path_base_for_github_subdir: content/en/developing-applications/develop-components/pluggable-components/pluggable-components-sdks/pluggable-components-go/ + github_branch: main +--- + +Dapr offers packages to help with the development of Go pluggable components. + +## Prerequisites + +- [Go 1.20](https://go.dev/dl/) or later +- [Dapr 1.9 CLI]({{% ref install-dapr-cli.md %}}) or later +- Initialized [Dapr environment]({{% ref install-dapr-selfhost.md %}}) +- Linux, Mac, or Windows (with WSL) + +{{% alert title="Note" color="primary" %}} +Development of Dapr pluggable components on Windows requires WSL. Not all languages and SDKs expose Unix Domain Sockets on "native" Windows. +{{% /alert %}} + +## Application creation + +Creating a pluggable component starts with an empty Go application. + +```bash +mkdir example +cd example +go mod init example +``` + +## Import Dapr packages + +Import the Dapr pluggable components SDK package. + +```bash +go get github.com/dapr-sandbox/components-go-sdk@v0.1.0 +``` + +## Create main package + +In `main.go`, import the Dapr plugggable components package and run the application. + +```go +package main + +import ( + dapr "github.com/dapr-sandbox/components-go-sdk" +) + +func main() { + dapr.MustRun() +} +``` + +This creates an application with no components. You will need to implement and register one or more components. + +## Implement and register components + + - [Implementing an input/output binding component]({{% ref go-bindings %}}) + - [Implementing a pub/sub component]({{% ref go-pub-sub %}}) + - [Implementing a state store component]({{% ref go-state-store %}}) + +{{% alert title="Note" color="primary" %}} +Only a single component of each type can be registered with an individual service. However, [multiple components of the same type can be spread across multiple services]({{% ref go-advanced %}}). +{{% /alert %}} + +## Test components locally + +### Create the Dapr components socket directory + +Dapr communicates with pluggable components via Unix Domain Sockets files in a common directory. By default, both Dapr and pluggable components use the `/tmp/dapr-components-sockets` directory. You should create this directory if it does not already exist. + +```bash +mkdir /tmp/dapr-components-sockets +``` + +### Start the pluggable component + +Pluggable components can be tested by starting the application on the command line. + +To start the component, in the application directory: + +```bash +go run main.go +``` + +### Configure Dapr to use the pluggable component + +To configure Dapr to use the component, create a component YAML file in the resources directory. For example, for a state store component: + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: +spec: + type: state. + version: v1 + metadata: + - name: key1 + value: value1 + - name: key2 + value: value2 +``` + +Any `metadata` properties will be passed to the component via its `Store.Init(metadata state.Metadata)` method when the component is instantiated. + +### Start Dapr + +To start Dapr (and, optionally, the service making use of the service): + +```bash +dapr run --app-id --resources-path ... +``` + +At this point, the Dapr sidecar will have started and connected via Unix Domain Socket to the component. You can then interact with the component either: +- Through the service using the component (if started), or +- By using the Dapr HTTP or gRPC API directly + +## Create container + +Pluggable components are deployed as containers that run as sidecars to the application (like Dapr itself). A typical `Dockerfile` for creating a Docker image for a Go application might look like: + +```dockerfile +FROM golang:1.20-alpine AS builder + +WORKDIR /usr/src/app + +# Download dependencies +COPY go.mod go.sum ./ +RUN go mod download && go mod verify + +# Build the application +COPY . . +RUN go build -v -o /usr/src/bin/app . + +FROM alpine:latest + +# Setup non-root user and permissions +RUN addgroup -S app && adduser -S app -G app +RUN mkdir /tmp/dapr-components-sockets && chown app /tmp/dapr-components-sockets + +# Copy application to runtime image +COPY --from=builder --chown=app /usr/src/bin/app /app + +USER app + +CMD ["/app"] +``` + +Build the image: + +```bash +docker build -f Dockerfile -t : . +``` + +{{% alert title="Note" color="primary" %}} +Paths for `COPY` operations in the `Dockerfile` are relative to the Docker context passed when building the image, while the Docker context itself will vary depending on the needs of the application being built. In the example above, the assumption is that the Docker context is the component application directory. +{{% /alert %}} + +## Next steps +- [Advanced techniques with the pluggable components Go SDK]({{% ref go-advanced %}}) +- Learn more about implementing: + - [Bindings]({{% ref go-bindings %}}) + - [State]({{% ref go-state-store %}}) + - [Pub/sub]({{% ref go-pub-sub %}}) diff --git a/sdkdocs/pluggable-components/go/content/en/go-sdk-docs/go-advanced/_index.md b/sdkdocs/pluggable-components/go/content/en/go-sdk-docs/go-advanced/_index.md new file mode 100644 index 00000000000..800827841ea --- /dev/null +++ b/sdkdocs/pluggable-components/go/content/en/go-sdk-docs/go-advanced/_index.md @@ -0,0 +1,76 @@ +--- +type: docs +title: "Advanced uses of the Dapr pluggable components .Go SDK" +linkTitle: "Advanced" +weight: 2000 +description: How to use advanced techniques with the Dapr pluggable components Go SDK +is_preview: true +--- + +While not typically needed by most, these guides show advanced ways you can configure your Go pluggable components. + +## Component lifetime + +Pluggable components are registered by passing a "factory method" that is called for each configured Dapr component of that type associated with that socket. The method returns the instance associated with that Dapr component (whether shared or not). This allows multiple Dapr components of the same type to be configured with different sets of metadata, when component operations need to be isolated from one another, etc. + +## Registering multiple services + +Each call to `Register()` binds a socket to a registered pluggable component. One of each component type (input/output binding, pub/sub, and state store) can be registered per socket. + +```go +func main() { + dapr.Register("service-a", dapr.WithStateStore(func() state.Store { + return &components.MyDatabaseStoreComponent{} + })) + + dapr.Register("service-a", dapr.WithOutputBinding(func() bindings.OutputBinding { + return &components.MyDatabaseOutputBindingComponent{} + })) + + dapr.Register("service-b", dapr.WithStateStore(func() state.Store { + return &components.MyDatabaseStoreComponent{} + })) + + dapr.MustRun() +} +``` + +In the example above, a state store and output binding is registered with the socket `service-a` while another state store is registered with the socket `service-b`. + +## Configuring Multiple Components + +Configuring Dapr to use the hosted components is the same as for any single component - the component YAML refers to the associated socket. For example, to configure Dapr state stores for the two components registered above (to sockets `service-a` and `service-b`), you create two configuration files, each referencing their respective socket. + +```yaml +# +# This component uses the state store associated with socket `service-a` +# +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: state-store-a +spec: + type: state.service-a + version: v1 + metadata: [] +``` + +```yaml +# +# This component uses the state store associated with socket `service-b` +# +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: state-store-b +spec: + type: state.service-b + version: v1 + metadata: [] +``` + +## Next steps +- Learn more about implementing: + - [Bindings]({{% ref go-bindings %}}) + - [State]({{% ref go-state-store %}}) + - [Pub/sub]({{% ref go-pub-sub %}}) diff --git a/sdkdocs/pluggable-components/go/content/en/go-sdk-docs/go-bindings/_index.md b/sdkdocs/pluggable-components/go/content/en/go-sdk-docs/go-bindings/_index.md new file mode 100644 index 00000000000..bd7b4500fdc --- /dev/null +++ b/sdkdocs/pluggable-components/go/content/en/go-sdk-docs/go-bindings/_index.md @@ -0,0 +1,131 @@ +--- +type: docs +title: "Implementing a Go input/output binding component" +linkTitle: "Bindings" +weight: 1000 +description: How to create an input/output binding with the Dapr pluggable components Go SDK +no_list: true +is_preview: true +--- + +Creating a binding component requires just a few basic steps. + +## Import bindings packages + +Create the file `components/inputbinding.go` and add `import` statements for the state store related packages. + +```go +package components + +import ( + "context" + "github.com/dapr/components-contrib/bindings" +) +``` + +## Input bindings: Implement the `InputBinding` interface + +Create a type that implements the `InputBinding` interface. + +```go +type MyInputBindingComponent struct { +} + +func (component *MyInputBindingComponent) Init(meta bindings.Metadata) error { + // Called to initialize the component with its configured metadata... +} + +func (component *MyInputBindingComponent) Read(ctx context.Context, handler bindings.Handler) error { + // Until canceled, check the underlying store for messages and deliver them to the Dapr runtime... +} +``` + +Calls to the `Read()` method are expected to set up a long-lived mechanism for retrieving messages but immediately return `nil` (or an error, if that mechanism could not be set up). The mechanism should end when canceled (for example, via the `ctx.Done() or ctx.Err() != nil`). As messages are read from the underlying store of the component, they are delivered to the Dapr runtime via the `handler` callback, which does not return until the application (served by the Dapr runtime) acknowledges processing of the message. + +```go +func (b *MyInputBindingComponent) Read(ctx context.Context, handler bindings.Handler) error { + go func() { + for { + err := ctx.Err() + + if err != nil { + return + } + + messages := // Poll for messages... + + for _, message := range messages { + handler(ctx, &bindings.ReadResponse{ + // Set the message content... + }) + } + + select { + case <-ctx.Done(): + case <-time.After(5 * time.Second): + } + } + }() + + return nil +} +``` + +## Output bindings: Implement the `OutputBinding` interface + +Create a type that implements the `OutputBinding` interface. + +```go +type MyOutputBindingComponent struct { +} + +func (component *MyOutputBindingComponent) Init(meta bindings.Metadata) error { + // Called to initialize the component with its configured metadata... +} + +func (component *MyOutputBindingComponent) Invoke(ctx context.Context, req *bindings.InvokeRequest) (*bindings.InvokeResponse, error) { + // Called to invoke a specific operation... +} + +func (component *MyOutputBindingComponent) Operations() []bindings.OperationKind { + // Called to list the operations that can be invoked. +} +``` + +## Input and output binding components + +A component can be _both_ an input _and_ output binding. Simply implement both interfaces and register the component as both binding types. + +## Register binding component + +In the main application file (for example, `main.go`), register the binding component with the application. + +```go +package main + +import ( + "example/components" + dapr "github.com/dapr-sandbox/components-go-sdk" + "github.com/dapr-sandbox/components-go-sdk/bindings/v1" +) + +func main() { + // Register an import binding... + dapr.Register("my-inputbinding", dapr.WithInputBinding(func() bindings.InputBinding { + return &components.MyInputBindingComponent{} + })) + + // Register an output binding... + dapr.Register("my-outputbinding", dapr.WithOutputBinding(func() bindings.OutputBinding { + return &components.MyOutputBindingComponent{} + })) + + dapr.MustRun() +} +``` + +## Next steps +- [Advanced techniques with the pluggable components Go SDK]({{% ref go-advanced %}}) +- Learn more about implementing: + - [State]({{% ref go-state-store %}}) + - [Pub/sub]({{% ref go-pub-sub %}}) diff --git a/sdkdocs/pluggable-components/go/content/en/go-sdk-docs/go-pub-sub/_index.md b/sdkdocs/pluggable-components/go/content/en/go-sdk-docs/go-pub-sub/_index.md new file mode 100644 index 00000000000..b805b18aae9 --- /dev/null +++ b/sdkdocs/pluggable-components/go/content/en/go-sdk-docs/go-pub-sub/_index.md @@ -0,0 +1,113 @@ +--- +type: docs +title: "Implementing a Go pub/sub component" +linkTitle: "Pub/sub" +weight: 1000 +description: How to create a pub/sub component with the Dapr pluggable components Go SDK +no_list: true +is_preview: true +--- + +Creating a pub/sub component requires just a few basic steps. + +## Import pub/sub packages + +Create the file `components/pubsub.go` and add `import` statements for the pub/sub related packages. + +```go +package components + +import ( + "context" + "github.com/dapr/components-contrib/pubsub" +) +``` + +## Implement the `PubSub` interface + +Create a type that implements the `PubSub` interface. + +```go +type MyPubSubComponent struct { +} + +func (component *MyPubSubComponent) Init(metadata pubsub.Metadata) error { + // Called to initialize the component with its configured metadata... +} + +func (component *MyPubSubComponent) Close() error { + // Not used with pluggable components... + return nil +} + +func (component *MyPubSubComponent) Features() []pubsub.Feature { + // Return a list of features supported by the component... +} + +func (component *MyPubSubComponent) Publish(req *pubsub.PublishRequest) error { + // Send the message to the "topic"... +} + +func (component *MyPubSubComponent) Subscribe(ctx context.Context, req pubsub.SubscribeRequest, handler pubsub.Handler) error { + // Until canceled, check the topic for messages and deliver them to the Dapr runtime... +} +``` + +Calls to the `Subscribe()` method are expected to set up a long-lived mechanism for retrieving messages but immediately return `nil` (or an error, if that mechanism could not be set up). The mechanism should end when canceled (for example, via the `ctx.Done()` or `ctx.Err() != nil`). The "topic" from which messages should be pulled is passed via the `req` argument, while the delivery to the Dapr runtime is performed via the `handler` callback. The callback doesn't return until the application (served by the Dapr runtime) acknowledges processing of the message. + +```go +func (component *MyPubSubComponent) Subscribe(ctx context.Context, req pubsub.SubscribeRequest, handler pubsub.Handler) error { + go func() { + for { + err := ctx.Err() + + if err != nil { + return + } + + messages := // Poll for messages... + + for _, message := range messages { + handler(ctx, &pubsub.NewMessage{ + // Set the message content... + }) + } + + select { + case <-ctx.Done(): + case <-time.After(5 * time.Second): + } + } + }() + + return nil +} +``` + +## Register pub/sub component + +In the main application file (for example, `main.go`), register the pub/sub component with the application. + +```go +package main + +import ( + "example/components" + dapr "github.com/dapr-sandbox/components-go-sdk" + "github.com/dapr-sandbox/components-go-sdk/pubsub/v1" +) + +func main() { + dapr.Register("", dapr.WithPubSub(func() pubsub.PubSub { + return &components.MyPubSubComponent{} + })) + + dapr.MustRun() +} +``` + +## Next steps +- [Advanced techniques with the pluggable components Go SDK]({{% ref go-advanced %}}) +- Learn more about implementing: + - [Bindings]({{% ref go-bindings %}}) + - [State]({{% ref go-state-store %}}) diff --git a/sdkdocs/pluggable-components/go/content/en/go-sdk-docs/go-state-store/_index.md b/sdkdocs/pluggable-components/go/content/en/go-sdk-docs/go-state-store/_index.md new file mode 100644 index 00000000000..54b66e32450 --- /dev/null +++ b/sdkdocs/pluggable-components/go/content/en/go-sdk-docs/go-state-store/_index.md @@ -0,0 +1,147 @@ +--- +type: docs +title: "Implementing a Go state store component" +linkTitle: "State Store" +weight: 1000 +description: How to create a state store with the Dapr pluggable components Go SDK +no_list: true +is_preview: true +--- + +Creating a state store component requires just a few basic steps. + +## Import state store packages + +Create the file `components/statestore.go` and add `import` statements for the state store related packages. + +```go +package components + +import ( + "context" + "github.com/dapr/components-contrib/state" +) +``` + +## Implement the `Store` interface + +Create a type that implements the `Store` interface. + +```go +type MyStateStore struct { +} + +func (store *MyStateStore) Init(metadata state.Metadata) error { + // Called to initialize the component with its configured metadata... +} + +func (store *MyStateStore) GetComponentMetadata() map[string]string { + // Not used with pluggable components... + return map[string]string{} +} + +func (store *MyStateStore) Features() []state.Feature { + // Return a list of features supported by the state store... +} + +func (store *MyStateStore) Delete(ctx context.Context, req *state.DeleteRequest) error { + // Delete the requested key from the state store... +} + +func (store *MyStateStore) Get(ctx context.Context, req *state.GetRequest) (*state.GetResponse, error) { + // Get the requested key value from the state store, else return an empty response... +} + +func (store *MyStateStore) Set(ctx context.Context, req *state.SetRequest) error { + // Set the requested key to the specified value in the state store... +} + +func (store *MyStateStore) BulkGet(ctx context.Context, req []state.GetRequest) (bool, []state.BulkGetResponse, error) { + // Get the requested key values from the state store... +} + +func (store *MyStateStore) BulkDelete(ctx context.Context, req []state.DeleteRequest) error { + // Delete the requested keys from the state store... +} + +func (store *MyStateStore) BulkSet(ctx context.Context, req []state.SetRequest) error { + // Set the requested keys to their specified values in the state store... +} +``` + +## Register state store component + +In the main application file (for example, `main.go`), register the state store with an application service. + +```go +package main + +import ( + "example/components" + dapr "github.com/dapr-sandbox/components-go-sdk" + "github.com/dapr-sandbox/components-go-sdk/state/v1" +) + +func main() { + dapr.Register("", dapr.WithStateStore(func() state.Store { + return &components.MyStateStoreComponent{} + })) + + dapr.MustRun() +} +``` + +## Bulk state stores + +While state stores are required to support the [bulk operations]({{% ref "state-management-overview.md#bulk-read-operations" %}}), their implementations sequentially delegate to the individual operation methods. + +## Transactional state stores + +State stores that intend to support transactions should implement the optional `TransactionalStore` interface. Its `Multi()` method receives a request with a sequence of `delete` and/or `set` operations to be performed within a transaction. The state store should iterate over the sequence and apply each operation. + +```go +func (store *MyStateStoreComponent) Multi(ctx context.Context, request *state.TransactionalStateRequest) error { + // Start transaction... + + for _, operation := range request.Operations { + switch operation.Operation { + case state.Delete: + deleteRequest := operation.Request.(state.DeleteRequest) + // Process delete request... + case state.Upsert: + setRequest := operation.Request.(state.SetRequest) + // Process set request... + } + } + + // End (or rollback) transaction... + + return nil +} +``` + +## Queryable state stores + +State stores that intend to support queries should implement the optional `Querier` interface. Its `Query()` method is passed details about the query, such as the filter(s), result limits, pagination, and sort order(s) of the results. The state store uses those details to generate a set of values to return as part of its response. + +```go +func (store *MyStateStoreComponent) Query(ctx context.Context, req *state.QueryRequest) (*state.QueryResponse, error) { + // Generate and return results... +} +``` + +## ETag and other semantic error handling + +The Dapr runtime has additional handling of certain error conditions resulting from some state store operations. State stores can indicate such conditions by returning specific errors from its operation logic: + +| Error | Applicable Operations | Description +|---|---|---| +| `NewETagError(state.ETagInvalid, ...)` | Delete, Set, Bulk Delete, Bulk Set | When an ETag is invalid | +| `NewETagError(state.ETagMismatch, ...)`| Delete, Set, Bulk Delete, Bulk Set | When an ETag does not match an expected value | +| `NewBulkDeleteRowMismatchError(...)` | Bulk Delete | When the number of affected rows does not match the expected rows | + +## Next steps +- [Advanced techniques with the pluggable components Go SDK]({{% ref go-advanced %}}) +- Learn more about implementing: + - [Bindings]({{% ref go-bindings %}}) + - [Pub/sub]({{% ref go-pub-sub %}})