Merge pull request #122 from dokku/9-implement-network-task

josegonzalez · web-flow · commit 5bbffc059669 · 2026-04-25T04:39:22.000-04:00
feat: implement dokku_network task
diff --git a/docs/dokku_network.md b/docs/dokku_network.md
@@ -0,0 +1,18 @@
+# dokku_network
+
+Creates or destroys a Docker network
+
+## Create a network named example-network
+
+```yaml
+dokku_network:
+    name: example-network
+```
+
+## Destroy a network named example-network
+
+```yaml
+dokku_network:
+    name: example-network
+    state: absent
+```
diff --git a/tasks/integration_test.go b/tasks/integration_test.go
@@ -204,6 +204,104 @@ func TestIntegrationAppCreateAndDestroy(t *testing.T) {
 	}
 }
 
+func dockerNetworkExists(name string) bool {
+	result, err := subprocess.CallExecCommand(subprocess.ExecCommandInput{
+		Command: "docker",
+		Args:    []string{"network", "inspect", name, "--format", "{{.Name}}"},
+	})
+	if err != nil {
+		return false
+	}
+	return strings.TrimSpace(result.StdoutContents()) == name
+}
+
+func TestIntegrationNetworkCreateAndDestroy(t *testing.T) {
+	skipIfNoDokkuT(t)
+
+	networkName := "omakase-test-network"
+
+	// ensure clean state
+	destroyNetwork(networkName)
+
+	// verify network does not exist via docker cli
+	if dockerNetworkExists(networkName) {
+		t.Fatal("expected network to not exist before creation")
+	}
+
+	// create the network
+	task := NetworkTask{Name: networkName, State: StatePresent}
+	result := task.Execute()
+	if result.Error != nil {
+		t.Fatalf("failed to create network: %v", result.Error)
+	}
+	if result.State != StatePresent {
+		t.Errorf("expected state 'present', got '%s'", result.State)
+	}
+	if !result.Changed {
+		t.Error("expected changed=true for new network creation")
+	}
+
+	// verify network exists via docker cli
+	if !dockerNetworkExists(networkName) {
+		t.Fatal("expected network to exist after creation")
+	}
+
+	// verify network driver via docker cli
+	inspectResult, err := subprocess.CallExecCommand(subprocess.ExecCommandInput{
+		Command: "docker",
+		Args:    []string{"network", "inspect", networkName, "--format", "{{.Driver}}"},
+	})
+	if err != nil {
+		t.Fatalf("failed to inspect network driver: %v", err)
+	}
+	driver := strings.TrimSpace(inspectResult.StdoutContents())
+	if driver != "bridge" {
+		t.Errorf("expected network driver 'bridge', got '%s'", driver)
+	}
+
+	// creating again should be idempotent
+	result = task.Execute()
+	if result.Error != nil {
+		t.Fatalf("idempotent create failed: %v", result.Error)
+	}
+	if result.Changed {
+		t.Error("expected changed=false for existing network")
+	}
+	if result.State != StatePresent {
+		t.Errorf("expected state 'present', got '%s'", result.State)
+	}
+
+	// destroy the network
+	destroyTask := NetworkTask{Name: networkName, State: StateAbsent}
+	result = destroyTask.Execute()
+	if result.Error != nil {
+		t.Fatalf("failed to destroy network: %v", result.Error)
+	}
+	if result.State != StateAbsent {
+		t.Errorf("expected state 'absent', got '%s'", result.State)
+	}
+	if !result.Changed {
+		t.Error("expected changed=true for network destruction")
+	}
+
+	// verify network does not exist via docker cli after destroy
+	if dockerNetworkExists(networkName) {
+		t.Fatal("expected network to not exist after destruction")
+	}
+
+	// destroying again should be idempotent
+	result = destroyTask.Execute()
+	if result.Error != nil {
+		t.Fatalf("idempotent destroy failed: %v", result.Error)
+	}
+	if result.Changed {
+		t.Error("expected changed=false for nonexistent network")
+	}
+	if result.State != StateAbsent {
+		t.Errorf("expected state 'absent', got '%s'", result.State)
+	}
+}
+
 func TestIntegrationConfigSetAndUnset(t *testing.T) {
 	skipIfNoDokkuT(t)
 
diff --git a/tasks/main_test.go b/tasks/main_test.go
@@ -160,6 +160,7 @@ func TestRegisteredTasksExist(t *testing.T) {
 		"dokku_domains_toggle",
 		"dokku_git_from_image",
 		"dokku_git_sync",
+		"dokku_network",
 		"dokku_network_property",
 		"dokku_ports",
 		"dokku_proxy_toggle",
@@ -847,3 +848,39 @@ func TestGetTasksServiceLinkWithTemplateContext(t *testing.T) {
 		t.Errorf("Name = %q, want %q", slTask.Name, "my-db")
 	}
 }
+
+func TestGetTasksNetworkTaskParsedCorrectly(t *testing.T) {
+	data := []byte(`---
+- tasks:
+    - name: create test network
+      dokku_network:
+        name: test-network
+`)
+	context := map[string]interface{}{}
+
+	tasks, err := GetTasks(data, context)
+	if err != nil {
+		t.Fatalf("GetTasks failed: %v", err)
+	}
+
+	task := tasks.Get("create test network")
+	if task == nil {
+		t.Fatal("task 'create test network' not found")
+	}
+
+	netTask, ok := task.(*NetworkTask)
+	if !ok {
+		nt, ok2 := task.(NetworkTask)
+		if !ok2 {
+			t.Fatalf("task is not a NetworkTask (type is %T)", task)
+		}
+		netTask = &nt
+	}
+
+	if netTask.Name != "test-network" {
+		t.Errorf("Name = %q, want %q", netTask.Name, "test-network")
+	}
+	if netTask.DesiredState() != StatePresent {
+		t.Errorf("expected default state 'present', got %q", netTask.DesiredState())
+	}
+}
diff --git a/tasks/network_task.go b/tasks/network_task.go
@@ -0,0 +1,169 @@
+package tasks
+
+import (
+	"fmt"
+	"omakase/subprocess"
+
+	yaml "gopkg.in/yaml.v3"
+)
+
+// NetworkTask creates or destroys a Docker network
+type NetworkTask struct {
+	// Name is the name of the network
+	Name string `required:"true" yaml:"name"`
+
+	// State is the state of the network
+	State State `required:"false" yaml:"state,omitempty" default:"present" options:"present,absent"`
+}
+
+// NetworkTaskExample contains an example of a NetworkTask
+type NetworkTaskExample struct {
+	// Name is the task name holding the NetworkTask description
+	Name string `yaml:"-"`
+
+	// DokkuNetwork is the NetworkTask configuration
+	DokkuNetwork NetworkTask `yaml:"dokku_network"`
+}
+
+// DesiredState returns the desired state of the network
+func (t NetworkTask) DesiredState() State {
+	return t.State
+}
+
+// Doc returns the docblock for the network task
+func (t NetworkTask) Doc() string {
+	return "Creates or destroys a Docker network"
+}
+
+// Examples returns a list of NetworkTaskExamples as yaml
+func (t NetworkTask) Examples() ([]Doc, error) {
+	examples := []NetworkTaskExample{
+		{
+			Name: "Create a network named example-network",
+			DokkuNetwork: NetworkTask{
+				Name: "example-network",
+			},
+		},
+		{
+			Name: "Destroy a network named example-network",
+			DokkuNetwork: NetworkTask{
+				Name:  "example-network",
+				State: "absent",
+			},
+		},
+	}
+
+	var output []Doc
+	for _, example := range examples {
+		b, err := yaml.Marshal(example)
+		if err != nil {
+			return nil, err
+		}
+
+		output = append(output, Doc{
+			Name:      example.Name,
+			Codeblock: string(b),
+		})
+	}
+
+	return output, nil
+}
+
+// Execute creates or destroys a Docker network
+func (t NetworkTask) Execute() TaskOutputState {
+	funcMap := map[State]func(string) TaskOutputState{
+		"present": createNetwork,
+		"absent":  destroyNetwork,
+	}
+
+	fn, ok := funcMap[t.State]
+	if !ok {
+		return TaskOutputState{
+			Error: fmt.Errorf("invalid state: %s", t.State),
+		}
+	}
+	return fn(t.Name)
+}
+
+// networkExists checks if a Docker network exists
+func networkExists(name string) bool {
+	result, err := subprocess.CallExecCommand(subprocess.ExecCommandInput{
+		Command: "dokku",
+		Args: []string{
+			"--quiet",
+			"network:exists",
+			name,
+		},
+	})
+	if err != nil {
+		return false
+	}
+
+	return result.ExitCode == 0
+}
+
+// createNetwork creates a Docker network
+func createNetwork(name string) TaskOutputState {
+	state := TaskOutputState{
+		Changed: false,
+		State:   "absent",
+	}
+	if networkExists(name) {
+		state.State = "present"
+		return state
+	}
+
+	result, err := subprocess.CallExecCommand(subprocess.ExecCommandInput{
+		Command: "dokku",
+		Args: []string{
+			"--quiet",
+			"network:create",
+			name,
+		},
+	})
+	if err != nil {
+		state.Error = err
+		state.Message = result.StderrContents()
+		return state
+	}
+
+	state.Changed = true
+	state.State = "present"
+	return state
+}
+
+// destroyNetwork destroys a Docker network
+func destroyNetwork(name string) TaskOutputState {
+	state := TaskOutputState{
+		Changed: false,
+		State:   "present",
+	}
+	if !networkExists(name) {
+		state.State = "absent"
+		return state
+	}
+
+	result, err := subprocess.CallExecCommand(subprocess.ExecCommandInput{
+		Command: "dokku",
+		Args: []string{
+			"--quiet",
+			"--force",
+			"network:destroy",
+			name,
+		},
+	})
+	if err != nil {
+		state.Error = err
+		state.Message = result.StderrContents()
+		return state
+	}
+
+	state.Changed = true
+	state.State = "absent"
+	return state
+}
+
+// init registers the NetworkTask with the task registry
+func init() {
+	RegisterTask(&NetworkTask{})
+}
diff --git a/tasks/task_execute_test.go b/tasks/task_execute_test.go
@@ -77,6 +77,26 @@ func TestGitFromImageTaskInvalidState(t *testing.T) {
 	}
 }
 
+func TestNetworkTaskInvalidState(t *testing.T) {
+	task := NetworkTask{Name: "test-network", State: "invalid"}
+	result := task.Execute()
+	if result.Error == nil {
+		t.Fatal("Execute with invalid state should return an error")
+	}
+}
+
+func TestNetworkTaskDesiredState(t *testing.T) {
+	task := NetworkTask{Name: "test-network", State: StatePresent}
+	if task.DesiredState() != StatePresent {
+		t.Errorf("expected state 'present', got '%s'", task.DesiredState())
+	}
+
+	task = NetworkTask{Name: "test-network", State: StateAbsent}
+	if task.DesiredState() != StateAbsent {
+		t.Errorf("expected state 'absent', got '%s'", task.DesiredState())
+	}
+}
+
 func TestNetworkPropertyTaskInvalidState(t *testing.T) {
 	task := NetworkPropertyTask{App: "test-app", Property: "attach-post-create", State: "invalid"}
 	result := task.Execute()
@@ -359,6 +379,8 @@ func TestAllTasksDesiredState(t *testing.T) {
 		{"DomainsToggleTask absent", &DomainsToggleTask{App: "test", State: StateAbsent}, StateAbsent},
 		{"GitFromImageTask deployed", &GitFromImageTask{App: "test", Image: "nginx", State: StateDeployed}, StateDeployed},
 		{"GitSyncTask present", &GitSyncTask{App: "test", Remote: "https://example.com/repo", State: StatePresent}, StatePresent},
+		{"NetworkTask present", &NetworkTask{Name: "test", State: StatePresent}, StatePresent},
+		{"NetworkTask absent", &NetworkTask{Name: "test", State: StateAbsent}, StateAbsent},
 		{"NetworkPropertyTask present", &NetworkPropertyTask{App: "test", Property: "bind-all-interfaces", State: StatePresent}, StatePresent},
 		{"NetworkPropertyTask absent", &NetworkPropertyTask{App: "test", Property: "bind-all-interfaces", State: StateAbsent}, StateAbsent},
 		{"PortsTask present", &PortsTask{App: "test", State: StatePresent}, StatePresent},
@@ -563,7 +585,7 @@ func TestAllTasksExamplesReturnNoError(t *testing.T) {
 }
 
 func TestRegisteredTaskCount(t *testing.T) {
-	expected := 17
+	expected := 18
 	if got := len(RegisteredTasks); got != expected {
 		t.Errorf("expected %d registered tasks, got %d", expected, got)
 	}
@@ -581,6 +603,7 @@ func TestTaskDocStrings(t *testing.T) {
 		{&DomainsToggleTask{}, "Enables or disables the domains plugin for a given dokku application"},
 		{&GitFromImageTask{}, "Deploys a git repository from a docker image"},
 		{&GitSyncTask{}, "Syncs a git repository to a dokku application"},
+		{&NetworkTask{}, "Creates or destroys a Docker network"},
 		{&NetworkPropertyTask{}, "Manages the network property for a given dokku application"},
 		{&PortsTask{}, "Manages the ports for a given dokku application"},
 		{&PsScaleTask{}, "Manages the process scale for a given dokku application"},
