docs: Add services section to cookbook (#7442)

* docs: Add services section to cookbook Signed-off-by: Vikram Vaswani <vikram@dagger.io> * Update copy Signed-off-by: Vikram Vaswani <vikram@dagger.io> * Update text Signed-off-by: Vikram Vaswani <vikram@dagger.io> * Updated paths Signed-off-by: Vikram Vaswani <vikram@dagger.io> * Update text Signed-off-by: Vikram Vaswani <vikram@dagger.io> * Update comments Signed-off-by: Vikram Vaswani <vikram@dagger.io> * Add feedback Signed-off-by: Vikram Vaswani <vikram@dagger.io> * Fix rebase Signed-off-by: Vikram Vaswani <vikram@dagger.io> * Fix linter Signed-off-by: Vikram Vaswani <vikram@dagger.io> * Updated heading Signed-off-by: Vikram Vaswani <vikram@dagger.io> * Cleanup go files for existing snippets Signed-off-by: Vikram Vaswani <vikram@dagger.io> * Update code comments format Signed-off-by: Vikram Vaswani <vikram@dagger.io> * Fix linter Signed-off-by: Vikram Vaswani <vikram@dagger.io> * Fix code, rebase Signed-off-by: Vikram Vaswani <vikram@dagger.io> * Fix linter Signed-off-by: Vikram Vaswani <vikram@dagger.io> * Move recipe location Signed-off-by: Vikram Vaswani <vikram@dagger.io> --------- Signed-off-by: Vikram Vaswani <vikram@dagger.io>
dagger · May 27, 2024 · c236d32 · c236d32
1 parent cc37cb6
commit c236d32
Show file tree

Hide file tree

Showing 50 changed files with 529 additions and 184 deletions.
diff --git a/docs/current_docs/manuals/developer/cookbook.mdx b/docs/current_docs/manuals/developer/cookbook.mdx
diff --git a/docs/current_docs/manuals/developer/cookbook/snippets/builds/matrix-build/go/main.go b/docs/current_docs/manuals/developer/cookbook/snippets/builds/matrix-build/go/main.go
@@ -10,8 +10,7 @@ type MyModule struct{}
 // Build and return directory of go binaries
 func (m *MyModule) Build(
 	ctx context.Context,
-	// source code location
-	// can be local directory or remote Git repository
+	// Source code location
 	src *Directory,
 ) *Directory {
 	// define build matrix

diff --git a/...ookbook/snippets/modify-dir/go/.gitignore → ...snippets/cache-dependencies/go/.gitignore b/...ookbook/snippets/modify-dir/go/.gitignore → ...snippets/cache-dependencies/go/.gitignore
diff --git a/docs/current_docs/manuals/developer/cookbook/snippets/cache-dependencies/go/main.go b/docs/current_docs/manuals/developer/cookbook/snippets/cache-dependencies/go/main.go
@@ -3,7 +3,10 @@ package main
 type MyModule struct{}
 
 // Build an application using cached dependencies
-func (m *MyModule) Build(source *Directory) *Container {
+func (m *MyModule) Build(
+	// Source code location
+	source *Directory,
+) *Container {
 	return dag.Container().
 		From("golang:1.21").
 		WithDirectory("/src", source).

diff --git a/docs/current_docs/manuals/developer/cookbook/snippets/cache-dependencies/python/main.py b/docs/current_docs/manuals/developer/cookbook/snippets/cache-dependencies/python/main.py
@@ -1,11 +1,15 @@
+from typing import Annotated
+
 import dagger
-from dagger import dag, function, object_type
+from dagger import Doc, dag, function, object_type
 
 
 @object_type
 class MyModule:
     @function
-    def build(self, source: dagger.Directory) -> dagger.Container:
+    def build(
+        self, source: Annotated[dagger.Directory, Doc("Source code location")]
+    ) -> dagger.Container:
         """Build an application using cached dependencies"""
         return (
             dag.container()

diff --git a/docs/current_docs/manuals/developer/cookbook/snippets/cache-dependencies/typescript/index.ts b/docs/current_docs/manuals/developer/cookbook/snippets/cache-dependencies/typescript/index.ts
@@ -6,7 +6,12 @@ class MyModule {
    * Build an application using cached dependencies
    */
   @func()
-  build(source: Directory): Container {
+  build(
+    /**
+     * Source code location
+     */
+    source: Directory,
+  ): Container {
     return dag
       .container()
       .from("node:21")

diff --git a/...cookbook/snippets/write-dir/go/.gitignore → .../cookbook/snippets/copy-dir/go/.gitignore b/...cookbook/snippets/write-dir/go/.gitignore → .../cookbook/snippets/copy-dir/go/.gitignore
diff --git a/...okbook/snippets/modify-dir/go/dagger.json → ...cookbook/snippets/copy-dir/go/dagger.json b/...okbook/snippets/modify-dir/go/dagger.json → ...cookbook/snippets/copy-dir/go/dagger.json
diff --git a/...er/cookbook/snippets/modify-dir/go/go.mod → ...oper/cookbook/snippets/copy-dir/go/go.mod b/...er/cookbook/snippets/modify-dir/go/go.mod → ...oper/cookbook/snippets/copy-dir/go/go.mod
diff --git a/...er/cookbook/snippets/modify-dir/go/go.sum → ...oper/cookbook/snippets/copy-dir/go/go.sum b/...er/cookbook/snippets/modify-dir/go/go.sum → ...oper/cookbook/snippets/copy-dir/go/go.sum
diff --git a/docs/current_docs/manuals/developer/cookbook/snippets/copy-dir/go/main.go b/docs/current_docs/manuals/developer/cookbook/snippets/copy-dir/go/main.go
@@ -0,0 +1,18 @@
+package main
+
+import (
+	"context"
+)
+
+type MyModule struct{}
+
+// Return a container with a specified directory
+func (m *MyModule) CopyDirectory(
+	ctx context.Context,
+	// Source directory
+	source *Directory,
+) *Container {
+	return dag.Container().
+		From("alpine:latest").
+		WithDirectory("/src", source)
+}
diff --git a/docs/current_docs/manuals/developer/cookbook/snippets/copy-dir/python/main.py b/docs/current_docs/manuals/developer/cookbook/snippets/copy-dir/python/main.py
@@ -0,0 +1,14 @@
+from typing import Annotated
+
+import dagger
+from dagger import Doc, dag, function, object_type
+
+
+@object_type
+class MyModule:
+    @function
+    def copy_directory(
+        self, source: Annotated[dagger.Directory, Doc("Source directory")]
+    ) -> dagger.Container:
+        """Return a container with a specified directory"""
+        return dag.container().from_("alpine:latest").with_directory("/src", source)
diff --git a/...ok/snippets/write-dir/typescript/index.ts → ...ook/snippets/copy-dir/typescript/index.ts b/...ok/snippets/write-dir/typescript/index.ts → ...ook/snippets/copy-dir/typescript/index.ts
@@ -3,10 +3,15 @@ import { dag, Container, Directory, object, func } from "@dagger.io/dagger"
 @object()
 class MyModule {
   /**
-   * Returns a container with a specified directory
+   * Return a container with a specified directory
    */
   @func()
-  writeDirectory(d: Directory): Container {
-    return dag.container().from("alpine:latest").withDirectory("/src", d)
+  copyDirectory(
+    /**
+     * Source directory
+     */
+    source: Directory,
+  ): Container {
+    return dag.container().from("alpine:latest").withDirectory("/src", source)
   }
 }
diff --git a/docs/current_docs/manuals/developer/cookbook/snippets/copy-file/go/main.go b/docs/current_docs/manuals/developer/cookbook/snippets/copy-file/go/main.go
@@ -8,7 +8,11 @@ import (
 type MyModule struct{}
 
 // Return a container with a specified file
-func (m *MyModule) CopyFile(ctx context.Context, f *File) *Container {
+func (m *MyModule) CopyFile(
+	ctx context.Context,
+	// Source file
+	f *File,
+) *Container {
 	name, _ := f.Name(ctx)
 	return dag.Container().
 		From("alpine:latest").

diff --git a/docs/current_docs/manuals/developer/cookbook/snippets/copy-file/python/main.py b/docs/current_docs/manuals/developer/cookbook/snippets/copy-file/python/main.py
@@ -1,11 +1,16 @@
+from typing import Annotated
+
 import dagger
-from dagger import dag, function, object_type
+from dagger import Doc, dag, function, object_type
 
 
 @object_type
 class MyModule:
     @function
-    async def copy_file(self, f: dagger.File) -> dagger.Container:
+    async def copy_file(
+        self,
+        f: Annotated[dagger.File, Doc("Source file")],
+    ) -> dagger.Container:
         """Return a container with a specified file"""
         name = await f.name()
         return dag.container().from_("alpine:latest").with_file(f"/src/{name}", f)
diff --git a/docs/current_docs/manuals/developer/cookbook/snippets/copy-file/typescript/index.ts b/docs/current_docs/manuals/developer/cookbook/snippets/copy-file/typescript/index.ts
@@ -6,7 +6,12 @@ class MyModule {
    * Return a container with a specified file
    */
   @func()
-  async copyFile(f: File): Promise<Container> {
+  async copyFile(
+    /**
+     * Source file
+     */
+    f: File,
+  ): Promise<Container> {
     const name = await f.name()
     return dag.container().from("alpine:latest").withFile(`/src/${name}`, f)
   }

diff --git a/docs/current_docs/manuals/developer/cookbook/snippets/copy-modify-dir/go/.gitignore b/docs/current_docs/manuals/developer/cookbook/snippets/copy-modify-dir/go/.gitignore
@@ -0,0 +1,4 @@
+/dagger.gen.go
+/internal/dagger
+/internal/querybuilder
+/internal/telemetry
diff --git a/...ookbook/snippets/write-dir/go/dagger.json → ...k/snippets/copy-modify-dir/go/dagger.json b/...ookbook/snippets/write-dir/go/dagger.json → ...k/snippets/copy-modify-dir/go/dagger.json
diff --git a/...per/cookbook/snippets/write-dir/go/go.mod → ...okbook/snippets/copy-modify-dir/go/go.mod b/...per/cookbook/snippets/write-dir/go/go.mod → ...okbook/snippets/copy-modify-dir/go/go.mod
diff --git a/...per/cookbook/snippets/write-dir/go/go.sum → ...okbook/snippets/copy-modify-dir/go/go.sum b/...per/cookbook/snippets/write-dir/go/go.sum → ...okbook/snippets/copy-modify-dir/go/go.sum
diff --git a/docs/current_docs/manuals/developer/cookbook/snippets/copy-modify-dir/go/main.go b/docs/current_docs/manuals/developer/cookbook/snippets/copy-modify-dir/go/main.go
@@ -0,0 +1,19 @@
+package main
+
+import (
+	"context"
+)
+
+type MyModule struct{}
+
+// Return a container with a specified directory and an additional file
+func (m *MyModule) CopyAndModifyDirectory(
+	ctx context.Context,
+	// Source directory
+	source *Directory,
+) *Container {
+	return dag.Container().
+		From("alpine:latest").
+		WithDirectory("/src", source).
+		WithExec([]string{"/bin/sh", "-c", `echo foo > /src/foo`})
+}
diff --git a/docs/current_docs/manuals/developer/cookbook/snippets/copy-modify-dir/python/main.py b/docs/current_docs/manuals/developer/cookbook/snippets/copy-modify-dir/python/main.py
@@ -0,0 +1,19 @@
+from typing import Annotated
+
+import dagger
+from dagger import Doc, dag, function, object_type
+
+
+@object_type
+class MyModule:
+    @function
+    def copy_and_modify_directory(
+        self, source: Annotated[dagger.Directory, Doc("Source directory")]
+    ) -> dagger.Container:
+        """Return a container with a specified directory and an additional file"""
+        return (
+            dag.container()
+            .from_("alpine:latest")
+            .with_directory("/src", source)
+            .with_exec(["/bin/sh", "-c", "`echo foo > /src/foo`"])
+        )
diff --git a/...k/snippets/modify-dir/typescript/index.ts → ...ppets/copy-modify-dir/typescript/index.ts b/...k/snippets/modify-dir/typescript/index.ts → ...ppets/copy-modify-dir/typescript/index.ts
@@ -3,14 +3,19 @@ import { dag, Container, Directory, object, func } from "@dagger.io/dagger"
 @object()
 class MyModule {
   /**
-   * Returns a container with a specified directory and an additional file
+   * Return a container with a specified directory and an additional file
    */
   @func()
-  modifyDirectory(d: Directory): Container {
+  copyAndModifyDirectory(
+    /**
+     * Source directory
+     */
+    source: Directory,
+  ): Container {
     return dag
       .container()
       .from("alpine:latest")
-      .withDirectory("/src", d)
+      .withDirectory("/src", source)
       .withExec(["/bin/sh", "-c", "`echo foo > /src/foo`"])
   }
 }
diff --git a/docs/current_docs/manuals/developer/cookbook/snippets/modify-dir/go/main.go b/docs/current_docs/manuals/developer/cookbook/snippets/modify-dir/go/main.go
diff --git a/docs/current_docs/manuals/developer/cookbook/snippets/modify-dir/python/main.py b/docs/current_docs/manuals/developer/cookbook/snippets/modify-dir/python/main.py
diff --git a/docs/current_docs/manuals/developer/cookbook/snippets/set-env-vars/go/.gitignore b/docs/current_docs/manuals/developer/cookbook/snippets/set-env-vars/go/.gitignore
@@ -0,0 +1,4 @@
+/dagger.gen.go
+/internal/dagger
+/internal/querybuilder
+/internal/telemetry
diff --git a/docs/current_docs/manuals/developer/cookbook/snippets/write-dir/go/main.go b/docs/current_docs/manuals/developer/cookbook/snippets/write-dir/go/main.go
diff --git a/docs/current_docs/manuals/developer/cookbook/snippets/write-dir/python/main.py b/docs/current_docs/manuals/developer/cookbook/snippets/write-dir/python/main.py
diff --git a/docs/current_docs/manuals/developer/snippets/services/bind-services/go/main.go b/docs/current_docs/manuals/developer/snippets/services/bind-services/go/main.go
@@ -6,7 +6,7 @@ import (
 
 type MyModule struct{}
 
-// starts and returns an HTTP service
+// Start and return an HTTP service
 func (m *MyModule) HttpService() *Service {
 	return dag.Container().
 		From("python").
@@ -19,7 +19,7 @@ func (m *MyModule) HttpService() *Service {
 		AsService()
 }
 
-// sends a request to an HTTP service and returns the response
+// Send a request to an HTTP service and return the response
 func (m *MyModule) Get(ctx context.Context) (string, error) {
 	return dag.Container().
 		From("alpine").

diff --git a/docs/current_docs/manuals/developer/snippets/services/bind-services/python/main.py b/docs/current_docs/manuals/developer/snippets/services/bind-services/python/main.py
@@ -6,7 +6,7 @@
 class MyModule:
     @function
     def http_service(self) -> dagger.Service:
-        """Starts and returns an HTTP service."""
+        """Start and return an HTTP service."""
         return (
             dag.container()
             .from_("python")
@@ -19,7 +19,7 @@ def http_service(self) -> dagger.Service:
 
     @function
     async def get(self) -> str:
-        """Sends a request to an HTTP service and returns the response."""
+        """Send a request to an HTTP service and return the response."""
         return await (
             dag.container()
             .from_("alpine")

diff --git a/docs/current_docs/manuals/developer/snippets/services/bind-services/typescript/index.ts b/docs/current_docs/manuals/developer/snippets/services/bind-services/typescript/index.ts
@@ -3,7 +3,7 @@ import { dag, object, func, Service } from "@dagger.io/dagger"
 @object()
 class MyModule {
   /**
-   * Starts and returns an HTTP service
+   * Start and return an HTTP service
    */
   @func()
   httpService(): Service {
@@ -18,7 +18,7 @@ class MyModule {
   }
 
   /**
-   * Sends a request to an HTTP service and returns the response
+   * Send a request to an HTTP service and return the response
    */
   @func()
   async get(): Promise<string> {

diff --git a/...ent_docs/manuals/developer/snippets/services/expose-dagger-services-to-host/go/.gitignore b/...ent_docs/manuals/developer/snippets/services/expose-dagger-services-to-host/go/.gitignore
@@ -0,0 +1,4 @@
+/dagger.gen.go
+/internal/dagger
+/internal/querybuilder
+/internal/telemetry
diff --git a/...nt_docs/manuals/developer/snippets/services/expose-dagger-services-to-host/go/dagger.json b/...nt_docs/manuals/developer/snippets/services/expose-dagger-services-to-host/go/dagger.json
@@ -0,0 +1,6 @@
+{
+  "name": "my-module",
+  "sdk": "go",
+  "source": ".",
+  "engineVersion": "v0.11.3"
+}
diff --git a/...current_docs/manuals/developer/snippets/services/expose-dagger-services-to-host/go/go.mod b/...current_docs/manuals/developer/snippets/services/expose-dagger-services-to-host/go/go.mod
@@ -0,0 +1,13 @@
+module main
+
+go 1.21.7
+
+require (
+	github.com/99designs/gqlgen v0.17.31
+	github.com/Khan/genqlient v0.6.0
+	github.com/vektah/gqlparser/v2 v2.5.6
+	golang.org/x/exp v0.0.0-20231110203233-9a3e6036ecaa
+	golang.org/x/sync v0.6.0
+)
+
+require github.com/stretchr/testify v1.8.3 // indirect
diff --git a/...current_docs/manuals/developer/snippets/services/expose-dagger-services-to-host/go/go.sum b/...current_docs/manuals/developer/snippets/services/expose-dagger-services-to-host/go/go.sum
@@ -0,0 +1,35 @@
+github.com/99designs/gqlgen v0.17.31 h1:VncSQ82VxieHkea8tz11p7h/zSbvHSxSDZfywqWt158=
+github.com/99designs/gqlgen v0.17.31/go.mod h1:i4rEatMrzzu6RXaHydq1nmEPZkb3bKQsnxNRHS4DQB4=
+github.com/Khan/genqlient v0.6.0 h1:Bwb1170ekuNIVIwTJEqvO8y7RxBxXu639VJOkKSrwAk=
+github.com/Khan/genqlient v0.6.0/go.mod h1:rvChwWVTqXhiapdhLDV4bp9tz/Xvtewwkon4DpWWCRM=
+github.com/agnivade/levenshtein v1.1.1/go.mod h1:veldBMzWxcCG2ZvUTKD2kJNRdCk5hVbJomOvKkmgYbo=
+github.com/andreyvit/diff v0.0.0-20170406064948-c7f18ee00883 h1:bvNMNQO63//z+xNgfBlViaCIJKLlCJ6/fmUseuG0wVQ=
+github.com/andreyvit/diff v0.0.0-20170406064948-c7f18ee00883/go.mod h1:rCTlJbsFo29Kk6CurOXKm700vrz8f0KW0JNfpkRJY/8=
+github.com/arbovm/levenshtein v0.0.0-20160628152529-48b4e1c0c4d0/go.mod h1:t2tdKJDJF9BV14lnkjHmOQgcvEKgtqs5a1N3LNdJhGE=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/dgryski/trifles v0.0.0-20200323201526-dd97f9abfb48/go.mod h1:if7Fbed8SFyPtHLHbg49SI7NAdJiC5WIA09pe59rfAA=
+github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/sergi/go-diff v1.3.1 h1:xkr+Oxo4BOQKmkn/B9eMK0g5Kg/983T9DqqPHwYqD+8=
+github.com/sergi/go-diff v1.3.1/go.mod h1:aMJSSKb2lpPvRNec0+w3fl7LP9IOFzdc9Pa4NFbPK1I=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
+github.com/stretchr/testify v1.8.3 h1:RP3t2pwF7cMEbC1dqtB6poj3niw/9gnV4Cjg5oW5gtY=
+github.com/stretchr/testify v1.8.3/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+github.com/vektah/gqlparser/v2 v2.5.6 h1:Ou14T0N1s191eRMZ1gARVqohcbe1e8FrcONScsq8cRU=
+github.com/vektah/gqlparser/v2 v2.5.6/go.mod h1:z8xXUff237NntSuH8mLFijZ+1tjV1swDbpDqjJmk6ME=
+golang.org/x/exp v0.0.0-20231110203233-9a3e6036ecaa h1:FRnLl4eNAQl8hwxVVC17teOw8kdjVDVAiFMtgUdTSRQ=
+golang.org/x/exp v0.0.0-20231110203233-9a3e6036ecaa/go.mod h1:zk2irFbV9DP96SEBUUAy67IdHUaZuSnrz1n472HUCLE=
+golang.org/x/sync v0.6.0 h1:5BMeUDZ7vkXGfEr1x9B4bRcTH4lpkTkpdh0T/J+qjbQ=
+golang.org/x/sync v0.6.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=