feat(docs): add nodeadm wasm targets to call from docs

awslabs · Dec 10, 2024 · d427f75 · d427f75
1 parent da3591e
commit d427f75
Show file tree

Hide file tree

Showing 8 changed files with 125 additions and 6 deletions.
diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml
@@ -10,6 +10,14 @@ jobs:
       contents: write
     runs-on: ubuntu-latest
     steps:
+    - uses: actions/setup-go@41dfa10bad2bb2ae585af6ee5bb4d7d973ad74ed # 5.1.0
+    - run: |
+        pushd nodeadm
+        GOOS=js GOARCH=wasm go build -o nodeadm.wasm cmd/nodeadm-wasm/main.go
+        popd
+        mkdir -p ./site/assets/wasm && cp ./nodeadm/nodeadm.wasm ./site/assets/wasm/
+        mkdir -p ./site/assets/javascripts && cp "$(go env GOROOT)/misc/wasm/wasm_exec.js" ./site/assets/javascripts/
     - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # 4.2.2
     - run: pip install mkdocs mkdocs-material
-    - run: mkdocs gh-deploy --strict --no-history --force
+      # use the --dirty flag so that we dont purge our custom assets
+    - run: mkdocs gh-deploy --dirty --no-history --force
diff --git a/.gitignore b/.gitignore
@@ -5,3 +5,4 @@
 .DS_Store
 site/
 .git-commit
+*.wasm
diff --git a/doc/nodeadm/doc/playground.md b/doc/nodeadm/doc/playground.md
@@ -0,0 +1,57 @@
+# Playground
+
+This an interactive playground for `nodeadm`'s config parser packaged in the
+browser via WebAssembly!
+
+You can test out the validity of your EC2 Userdata and see any of the potential
+errors that might happen at runtime.
+
+<div>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/ace/1.36.5/ace.min.js" integrity="sha512-NIDAOLuPuewIzUrGoK5fXxowwGDm0DFJhI5TJPyTP6MeY2hUcCSKJr54fecQTEZ8kxxEO2NBrILQSUl4qZ37FA==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+    <script src="/amazon-eks-ami/assets/javascripts/wasm_exec.js"></script>
+    <body>
+        <div style="display: grid; margin: auto;">
+            <div id="editor" style="height:50vh"></div>
+            <textarea readonly style="height:15vh" id="response"></textarea>
+        </div>
+    </body>
+    <script>
+        const go = new Go();
+        WebAssembly.instantiateStreaming(fetch("/amazon-eks-ami/assets/wasm/nodeadm.wasm"), go.importObject).then((result) => {
+            go.run(result.instance);
+        });
+        const editor = ace.edit("editor", {
+          useWorker: false
+        });
+        editor.setTheme("ace/theme/monokai");
+        editor.session.setValue(`
+MIME-Version: 1.0
+Content-Type: multipart/mixed; boundary="BOUNDARY"
+
+--BOUNDARY
+Content-Type: application/node.eks.aws
+
+---
+apiVersion: node.eks.aws/v1alpha1
+kind: NodeConfig
+spec:
+  cluster:
+    name: my-cluster
+    apiServerEndpoint: https://example.com
+    certificateAuthority: Y2VydGlmaWNhdGVBdXRob3JpdHk=
+    cidr: 10.100.0.0/16
+  kubelet:
+    config:
+      shutdownGracePeriod: 30s
+      featureGates:
+        DisableKubeletCloudCredentialProviders: true
+
+--BOUNDARY--`.trim());
+        editor.session.setMode("ace/mode/yaml");
+        editor.setShowPrintMargin(false);
+        // editor is exposed via a global created by the monaco webcomponent
+        const validate = () => document.getElementById("response").textContent = nodeadmCheck(editor.session.getValue())
+        editor.session.on('change', function(_) { validate() });
+        validate()
+    </script>
+</div>
diff --git a/mkdocs.yaml b/mkdocs.yaml
@@ -20,6 +20,7 @@ nav:
       - 'Concepts': nodeadm/doc/api-concepts.md
       - 'Reference': nodeadm/doc/api.md
     - 'Examples': nodeadm/doc/examples.md
+    - 'Playground': nodeadm/doc/interactive.md
 theme:
   name: material
   palette:

diff --git a/nodeadm/cmd/nodeadm-wasm/main.go b/nodeadm/cmd/nodeadm-wasm/main.go
@@ -0,0 +1,52 @@
+//go:build wasm
+
+package main
+
+import (
+	"fmt"
+	"syscall/js"
+
+	"github.com/awslabs/amazon-eks-ami/nodeadm/internal/api"
+	"github.com/awslabs/amazon-eks-ami/nodeadm/internal/configprovider"
+)
+
+type jsWrapperFunc = func(this js.Value, args []js.Value) any
+
+func main() {
+	for jsFuncName, jsFunc := range map[string]jsWrapperFunc{
+		"nodeadmCheck": nodeadmCheckFunc,
+	} {
+		fmt.Printf("loading %q from Go WASM module\n", jsFuncName)
+		js.Global().Set(jsFuncName, js.FuncOf(func(this js.Value, args []js.Value) any {
+			defer func() {
+				// Since we cannot return errors in proper convention back to
+				// javascript through the WebAssembly Goroutine, we'll wrap the
+				// panic handler instead and print the information to keep the
+				// execution Go-like.
+				if r := recover(); r != nil {
+					errString := fmt.Sprintf("%s", r)
+					fmt.Printf("encountered error: %s\n", errString)
+					js.Global().Call("alert", errString)
+				}
+			}()
+			return jsFunc(this, args)
+		}))
+	}
+	// block function completion to keep the Go routines loaded in memory
+	<-make(chan struct{})
+}
+
+var nodeadmCheckFunc = func(this js.Value, args []js.Value) any {
+	if len(args) != 1 {
+		panic("incorrect number of arguments.")
+	}
+	document := args[0].String()
+	nodeConfig, err := configprovider.ParseMaybeMultipart([]byte(document))
+	if err != nil {
+		return js.ValueOf(err.Error())
+	}
+	if err := api.ValidateNodeConfig(nodeConfig); err != nil {
+		return js.ValueOf(fmt.Errorf("validating NodeConfig: %w", err).Error())
+	}
+	return js.ValueOf("Looks Good! 👍")
+}
diff --git a/nodeadm/internal/configprovider/file.go b/nodeadm/internal/configprovider/file.go
@@ -35,5 +35,5 @@ func (fcs *fileConfigProvider) Provide() (*internalapi.NodeConfig, error) {
 	if err != nil {
 		return nil, err
 	}
-	return parseMaybeMultipart(data)
+	return ParseMaybeMultipart(data)
 }
diff --git a/nodeadm/internal/configprovider/mime.go b/nodeadm/internal/configprovider/mime.go
@@ -13,11 +13,11 @@ import (
 	apibridge "github.com/awslabs/amazon-eks-ami/nodeadm/internal/api/bridge"
 )
 
-func parseMaybeMultipart(data []byte) (*internalapi.NodeConfig, error) {
+func ParseMaybeMultipart(data []byte) (*internalapi.NodeConfig, error) {
 	// if the MIME data fails to parse as a multipart document, then fall back
 	// to parsing the entire userdata as the node config.
 	if multipartReader, err := getMultipartReader(data); err == nil {
-		config, err := parseMultipart(multipartReader)
+		config, err := ParseMultipart(multipartReader)
 		if err != nil {
 			return nil, err
 		}
@@ -31,7 +31,7 @@ func parseMaybeMultipart(data []byte) (*internalapi.NodeConfig, error) {
 	}
 }
 
-func parseMultipart(userDataReader *multipart.Reader) (*internalapi.NodeConfig, error) {
+func ParseMultipart(userDataReader *multipart.Reader) (*internalapi.NodeConfig, error) {
 	var nodeConfigs []*internalapi.NodeConfig
 	for {
 		part, err := userDataReader.NextPart()

diff --git a/nodeadm/internal/configprovider/userdata.go b/nodeadm/internal/configprovider/userdata.go
@@ -49,5 +49,5 @@ func (p *userDataConfigProvider) Provide() (*internalapi.NodeConfig, error) {
 	if err != nil {
 		return nil, fmt.Errorf("failed to decompress user data: %v", err)
 	}
-	return parseMaybeMultipart(userData)
+	return ParseMaybeMultipart(userData)
 }
-Original file line number
+Diff line change
@@ Expand Up / @@ -5,3 +5,4 @@ @@
     .DS_Store
     site/
     .git-commit
+    *.wasm