8.1 KiB

Raw Blame History

Developing new component

This document describes how to build and test new components. The Dapr runtime and all of its components are written in Go. If you are completely new to the language you can take a tour of its features. For building your first component, using an existing one as a template is as a great way to get started.

Prerequisites

Clone dapr and component-contrib

We recommend creating a folder for Dapr and clone all repositories in that folder.

mkdir dapr

# Clone dapr
git clone https://github.com/dapr/dapr.git dapr/dapr

# Clone component-contrib
git clone https://github.com/dapr/components-contrib.git dapr/components-contrib

Writing new component

Write new component

Create your component directory in the right component directory
Copy component files from the reference component to your component directory
Add go unit-test for your component
Add conformance tests for your component.

Type	Directory	Reference	Docs
State	components-contrib/state	Redis	concept, howto, api spec
Pubsub	components-contrib/pubsub	Redis	concept, howto, api spec
Bindings	components-contrib/bindings	Kafka	concept, input howto, output howto, api spec
Secret Store	components-contrib/secretstore	Kubernetes, Azure Keyvault	concept, howto
Middleware	components-contrib/middleware	Oauth2	concept, howto
Name Resolution	components-contrib/nameresolution	mdns	howto

Running unit-test

make test

Running linting

make lint

Validating with Dapr core

Make sure you clone the dapr/dapr and dapr/component-contrib repositories side-by-side
Replace github.com/dapr/components-contrib reference to the locally-cloned component-contrib
```
go mod edit -replace github.com/dapr/components-contrib=../components-contrib
```
Import your component to dapr cmd/daprd/main.go
Register your component in dapr cmd/daprd/main.go(e.g. binding)
Build debuggable dapr binary
```
make modtidy-all
make DEBUG=1 build
```
Replace the installed daprd with the test binary (then dapr cli will use the test binary)
```
# Back up the current daprd
cp ~/.dapr/bin/daprd ~/.dapr/bin/daprd.bak
cp ./dist/darwin_amd64/debug/daprd ~/.dapr/bin
```
Linux debuggable binary: ./dist/linux_amd64/debug/daprd Windows debuggable binary: .\dist\windows_amd64\debug\daprd macOS (Intel) debuggable binary: ./dist/darwin_amd64/debug/daprd macOS (Apple Silicon) debuggable binary: ./dist/darwin_arm64/debug/daprd
Prepare your test app (e.g. kafka sample app: https://github.com/dapr/quickstarts/tree/master/bindings/nodeapp/)
Create YAML for bindings in './components' under app's directory (e.g. kafka example: https://github.com/dapr/quickstarts/blob/master/bindings/components/kafka_bindings.yaml)
Run your test app using Dapr cli
Make sure your component is loaded successfully in daprd log

Submit your component

Create a Pull Request to add your component in component-contrib repo
Get the approval from maintainers
Fetch the latest dapr/dapr repo
Update component-contrib in dapr/dapr's go.mod and ensure that component-contrib is updated to the latest version
```
go get -u github.com/dapr/components-contrib@master
make modtidy-all
```
Import your component to dapr cmd/daprd/main.go
Register your component in dapr cmd/daprd/main.go(e.g. binding)
Create a pullrequest in dapr/dapr

Version 2 and beyond of a component

API versioning of Dapr components follows the same approach as Go modules where the unstable version (v0) and first stable version (v1) are contained in the root directory of the component package. For example v1 of the Redis binding component is located in bindings/redis. Code changes may continue in this package provided there are no breaking changes. Breaking changes include:

Renaming or removing a metadata field that the component is currently using
Adding a required metadata field
Adding an optional field that does not have a backwards-compatible default value
Making significant changes to the component's behavior that would adversely affect existing users

In most cases, breaking changes can be avoided by using backward compatible metadata fields. When breaking changes cannot be avoided, here are the steps for creating the next major version of a component:

Create a version subdirectory for the next major version (e.g. bindings/redis/v2, bindings/redis/v3, etc.)
Copy any code into the new subdirectory that should be preserved from the previous version
Submit your component as described in the previous section
Import your component to Dapr cmd/daprd/main.go without removing the package for the previous version
Register your component in Dapr cmd/daprd/main.go like before, but append its new major version to the name (e.g. redis/v2)
Validate your component as described previously

8.1 KiB Raw Blame History