PoC: Dapr module

.github/dependabot.yml

@@ -93,6 +93,13 @@ updates:
         day: sunday
       open-pull-requests-limit: 3
       rebase-strategy: disabled
+    - package-ecosystem: gomod
+      directory: /modules/dapr
+      schedule:
+        interval: monthly
+        day: sunday
+      open-pull-requests-limit: 3
+      rebase-strategy: disabled
     - package-ecosystem: gomod
       directory: /modules/elasticsearch
       schedule:

.github/workflows/ci.yml

@@ -106,7 +106,7 @@ jobs:
       matrix:
         go-version: [1.20.x, 1.x]
         platform: [ubuntu-latest, macos-latest]
-        module: [artemis, cassandra, clickhouse, compose, couchbase, elasticsearch, gcloud, k3s, k6, kafka, localstack, mariadb, mongodb, mysql, nats, neo4j, postgres, pulsar, rabbitmq, redis, redpanda, vault]
+        module: [artemis, cassandra, clickhouse, compose, couchbase, dapr, elasticsearch, gcloud, k3s, k6, kafka, localstack, mariadb, mongodb, mysql, nats, neo4j, postgres, pulsar, rabbitmq, redis, redpanda, vault]
         exclude:
           - go-version: 1.20.x
             module: compose

.vscode/.testcontainers-go.code-workspace

@@ -41,6 +41,10 @@
             "name": "module / couchbase",
             "path": "../modules/couchbase"
         },
+        {
+            "name": "module / dapr",
+            "path": "../modules/dapr"
+        },
         {
             "name": "module / elasticsearch",
             "path": "../modules/elasticsearch"

docs/modules/dapr.md

@@ -0,0 +1,101 @@
+# Dapr
+
+Not available until the next release of testcontainers-go <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
+
+## Introduction
+
+The Testcontainers module for Dapr.
+
+## Adding this module to your project dependencies
+
+Please run the following command to add the Dapr module to your Go dependencies:
+
+```
+go get github.com/testcontainers/testcontainers-go/modules/dapr
+```
+
+## Usage example
+
+<!--codeinclude-->
+[Creating a Dapr container](../../modules/dapr/examples_test.go) inside_block:runDaprContainer
+<!--/codeinclude-->
+
+## Module reference
+
+The Dapr module exposes one entrypoint function to create the Dapr container, and this function receives two parameters:
+
+```golang
+func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*DaprContainer, error)
+```
+
+- `context.Context`, the Go context.
+- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.
+
+This entrypoint function will create:
+
+- a Dapr network in which the Dapr container and all its components will be attached. Default name is `dapr-network`.
+- a Dapr container.
+- A component container for each component that has a Docker image defined. See [Components](#components) for more information.
+
+### Container Options
+
+When starting the Dapr container, you can pass options in a variadic way to configure it.
+
+#### Image
+
+If you need to set a different Dapr Docker image, you can use `testcontainers.WithImage` with a valid Docker image
+for Dapr. E.g. `testcontainers.WithImage("daprio/daprd:1.11.3")`.
+
+{% include "../features/common_functional_options.md" %}
+
+#### Application Name
+
+It's possible to define the application name used by Dapr with the `WithAppName(name string)` functional option. If not passed, the default value is `dapr-app`.
+
+#### Network Name
+
+It's possible to define the network name used by Dapr with the `WithNetworkName(name string)` functional option. If not passed, the default value is `dapr-network`.
+
+#### Components
+
+You can add components to the Dapr container with the `WithComponents(components ...Component)` functional option. If not passed, the default value is an empty map.
+
+The `Component` struct has the following fields:
+
+<!--codeinclude-->
+[Dapr Component](../../modules/dapr/options.go) inside_block:componentStruct
+<!--/codeinclude-->
+
+- The key used to internally identify a Component is the component name. E.g. `statestore`.
+- The image is the Docker image used by the component. E.g. `redis:6-alpine`.
+- Metadata it's a map of strings, where the key is the metadata name and the value is the metadata value. It will be used to render a YAML file with the component configuration.
+
+!!! info
+    Those components with a Docker image will be run as a separate container in the Dapr network, and using Dapr's container ID as the container network mode.
+
+Each component will result in a configuration file that will be uploaded to the Dapr container, under the `/components` directory. It's possible to change this file path with the `WithComponentsPath(path string)` functional option. If not passed, the default value is `/components`.
+
+The file will be named as the component name, and the content will be a YAML file with the following structure:
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+  kind: Component
+  metadata:
+    name: statestore
+  spec:
+    type: state.in-memory
+    version: v1
+  metadata:
+    - name: foo1
+      value: bar1
+    - name: foo2
+      value: bar2
+```
+
+### Container Methods
+
+The Dapr container exposes the following methods:
+
+#### GRPCPort
+
+This method returns the integer representation of the exposed port for the Dapr gRPC API, which internally is `50001`, and an error if something went wrong while retrieving the port.

file.go

@@ -41,7 +41,7 @@ func tarDir(src string, fileMode int64) (*bytes.Buffer, error) {
 
 	buffer := &bytes.Buffer{}
 
-	fmt.Printf(">> creating TAR file from directory: %s\n", src)
+	Logger.Printf(">> creating TAR file from directory: %s\n", src)
 
 	// tar > gzip > buffer
 	zr := gzip.NewWriter(buffer)

mkdocs.yml

@@ -67,6 +67,7 @@ nav:
         - modules/cassandra.md
         - modules/clickhouse.md
         - modules/couchbase.md
+        - modules/dapr.md
         - modules/elasticsearch.md
         - modules/gcloud.md
         - modules/k3s.md

modules/dapr/Makefile

@@ -0,0 +1,5 @@
+include ../../commons-test.mk
+
+.PHONY: test
+test:
+	$(MAKE) test-dapr

modules/dapr/dapr.go

@@ -0,0 +1,204 @@
+package dapr
+
+import (
+	"context"
+	_ "embed"
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/docker/docker/api/types/container"
+	"github.com/docker/go-connections/nat"
+
+	"github.com/testcontainers/testcontainers-go"
+)
+
+const (
+	// defaultComponentsPath is the path where the components are mounted in the Dapr container
+	defaultComponentsPath string = "/components"
+	defaultDaprPort       string = "50001/tcp"
+	defaultDaprAppName    string = "dapr-app"
+	// defaultDaprNetworkName is the name of the network created by the Dapr container, in which the app container is connected
+	// and all the components will be attached to.
+	defaultDaprNetworkName string = "dapr-network"
+)
+
+var (
+	//go:embed mounts/component.yaml.tpl
+	componentYamlTpl string
+
+	// componentsTmpDir is the directory where the components are created before being mounted in the container
+	componentsTmpDir string
+)
+
+// DaprContainer represents the Dapr container type used in the module
+type DaprContainer struct {
+	testcontainers.Container
+	Network             testcontainers.Network
+	ComponentContainers map[string]testcontainers.Container
+	Settings            options
+}
+
+// GRPCPort returns the port used by the Dapr container
+func (c *DaprContainer) GRPCPort(ctx context.Context) (int, error) {
+	port, err := c.MappedPort(ctx, nat.Port(defaultDaprPort))
+	if err != nil {
+		return 0, err
+	}
+
+	return port.Int(), nil
+}
+
+// Terminate terminates the Dapr container and removes the component containers and the Dapr network,
+// in that particular order.
+func (c *DaprContainer) Terminate(ctx context.Context) error {
+	if err := c.Container.Terminate(ctx); err != nil {
+		return fmt.Errorf("failed to terminate Dapr container %w", err)
+	}
+
+	for key, componentContainer := range c.ComponentContainers {
+		// do not terminate the component container if it has no image defined
+		if c.Settings.Components[key].Image == "" {
+			continue
+		}
+
+		if err := componentContainer.Terminate(ctx); err != nil {
+			return fmt.Errorf("failed to terminate component container %w", err)
+		}
+	}
+
+	if err := c.Network.Remove(ctx); err != nil {
+		return fmt.Errorf("failed to terminate Dapr network %w", err)
+	}
+
+	return nil
+}
+
+// RunContainer creates an instance of the Dapr container type, creating the following elements:
+// - a Dapr network
+// - a Dapr container
+// - a component container for each component defined in the options. The component must have an image defined.
+func RunContainer(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*DaprContainer, error) {
+	componentsTmpDir = filepath.Join(os.TempDir(), fmt.Sprintf("%d", time.Now().UnixMilli()), "components")
+	err := os.MkdirAll(componentsTmpDir, 0o700)
+	if err != nil {
+		return nil, err
+	}
+
+	// make sure the temporary components directory is removed after the container is run.
+	defer func() {
+		_ = os.Remove(componentsTmpDir)
+	}()
+
+	req := testcontainers.ContainerRequest{
+		Image:        "daprio/daprd:1.11.3",
+		ExposedPorts: []string{defaultDaprPort},
+	}
+
+	genericContainerReq := testcontainers.GenericContainerRequest{
+		ContainerRequest: req,
+		Started:          true,
+	}
+
+	settings := defaultOptions()
+	for _, opt := range opts {
+		if apply, ok := opt.(Option); ok {
+			apply(&settings)
+		}
+		opt.Customize(&genericContainerReq)
+	}
+
+	// Transfer the components to the container in the form of a YAML file for each component
+	if err := renderComponents(settings, &genericContainerReq); err != nil {
+		return nil, err
+	}
+
+	genericContainerReq.Cmd = []string{"./daprd", "-app-id", settings.AppName, "--dapr-listen-addresses=0.0.0.0", "-components-path", defaultComponentsPath}
+
+	nw, err := testcontainers.GenericNetwork(ctx, testcontainers.GenericNetworkRequest{
+		NetworkRequest: testcontainers.NetworkRequest{
+			Name: settings.NetworkName,
+		},
+	})
+	if err != nil {
+		return nil, fmt.Errorf("failed to create Dapr network: %w", err)
+	}
+
+	// attach Dapr container to the Dapr network
+	genericContainerReq.Networks = []string{settings.NetworkName}
+	// setting the network alias to the application name will make it easier to connect to the Dapr container
+	genericContainerReq.NetworkAliases = map[string][]string{
+		settings.NetworkName: {settings.AppName},
+	}
+
+	daprContainer, err := testcontainers.GenericContainer(ctx, genericContainerReq)
+	if err != nil {
+		return nil, err
+	}
+
+	// we must start the component containers in container mode, so that they can connect to the Dapr container
+	networkMode := fmt.Sprintf("container:%v", daprContainer.GetContainerID())
+
+	componentContainers := map[string]testcontainers.Container{}
+	for _, component := range settings.Components {
+		if component.Image == "" {
+			continue
+		}
+
+		componentContainer, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
+			ContainerRequest: testcontainers.ContainerRequest{
+				Image:    component.Image,
+				Networks: []string{settings.NetworkName},
+				NetworkAliases: map[string][]string{
+					settings.NetworkName: {component.Name},
+				},
+				HostConfigModifier: func(hc *container.HostConfig) {
+					hc.NetworkMode = container.NetworkMode(networkMode)
+				},
+			},
+			Started: true,
+		})
+		if err != nil {
+			return nil, err
+		}
+
+		componentContainers[component.Key()] = componentContainer
+	}
+
+	return &DaprContainer{
+		Container:           daprContainer,
+		Settings:            settings,
+		ComponentContainers: componentContainers,
+		Network:             nw,
+	}, nil
+}
+
+// renderComponents renders the configuration file for each component, creating a temporary file for each one under a default
+// temporary directory. The entire directory is then uploaded to the container, including the
+// right permissions (0o777) for Dapr to access the files.
+func renderComponents(settings options, req *testcontainers.GenericContainerRequest) error {
+	execPermissions := os.FileMode(0o777)
+
+	for _, component := range settings.Components {
+		content, err := component.Render()
+		if err != nil {
+			return err
+		}
+
+		tmpComponentFile := filepath.Join(componentsTmpDir, component.FileName())
+		err = os.WriteFile(tmpComponentFile, content, execPermissions)
+		if err != nil {
+			return err
+		}
+
+	}
+
+	req.Files = append(req.Files, testcontainers.ContainerFile{
+		HostFilePath:      componentsTmpDir,
+		ContainerFilePath: defaultComponentsPath,
+		FileMode:          int64(execPermissions),
+	})
+
+	return nil
+}