initial commit for sandboxes pages (#2754)

Co-authored-by: Phil Hawksworth <phil@deno.com>
Co-authored-by: Ryan Dahl <ry@tinyclouds.org>
Co-authored-by: Luca Casonato <hello@lcas.dev>
Co-authored-by: Marvin Hagemeister <marvin@deno.com>

Author: 5 people

_components/Header.tsx

@@ -11,7 +11,7 @@ export default function (
   const hrefIsInCurrentSection = (href: string, currentSection: string) => {
     return href.includes(currentSection) ||
       href === "/services/" &&
-        ["deploy", "subhosting", "services"].includes(
+        ["deploy", "subhosting", "services", "sandboxes"].includes(
           currentSection,
         );
   };

_config.ts

@@ -140,6 +140,7 @@ site.copy("deploy/images");
 site.copy("deploy/classic/images");
 site.copy("deploy/kv/images");
 site.copy("deploy/tutorials/images");
+site.copy("sandboxes/images");
 site.copy("runtime/fundamentals/images");
 site.copy("runtime/getting_started/images");
 site.copy("runtime/reference/images");

_includes/layout.tsx

@@ -10,7 +10,8 @@ export default function Layout(data: Lume.Data) {
     "In-depth documentation, guides, and reference materials for building secure, high-performance JavaScript and TypeScript applications with Deno";
   const isServicesPage = data.url.startsWith("/deploy") ||
     data.url.startsWith("/subhosting") ||
-    data.url.startsWith("/services");
+    data.url.startsWith("/services") ||
+    data.url.startsWith("/sandboxes");
   const hasSubNav = isServicesPage;
 
   return (

_includes/sandbox-example.tsx

@@ -0,0 +1,21 @@
+export const layout = "doc.tsx";
+
+export default function Raw(data: Lume.Data) {
+  return (
+    <>
+      <p className="italic">
+        <a href="https://deno.com/deploy/sandboxes/">Deno Sandboxes</a>{" "}
+        provide a sandboxed environment for evaluating JavaScript code. This is
+        useful for evaluating code that is not trusted or for testing code that
+        is not safe to run in the main runtime.
+      </p>
+
+      {data.children}
+
+      <p className="my-8 block">
+        For more information about Sandboxes, see the{" "}
+        <a href="/sandboxes/">Sandboxes documentation</a>.
+      </p>
+    </>
+  );
+}

deno.lock

@@ -153,6 +153,10 @@ export const SidebarNav = [
     title: "Deno Deploy",
     href: "/deploy/",
   },
+  {
+    title: "Sandboxes",
+    href: "/sandboxes/",
+  },
   {
     title: "Deploy Classic",
     href: "/deploy/classic/",

deploy/_data.ts

@@ -124,6 +124,10 @@ export const SidebarNav = [
     title: "Deno Deploy",
     href: "/deploy/",
   },
+  {
+    title: "Sandboxes",
+    href: "/sandboxes/",
+  },
   {
     title: "Deploy Classic",
     href: "/deploy/classic/",

deploy/classic/_data.ts

@@ -300,6 +300,91 @@ export const sidebar = [
       },
     ],
   },
+  {
+    title: "Sandboxes",
+    items: [
+      {
+        title: "Evaluating JavaScript",
+        href: "/examples/sandboxes_evaluating_javascript/",
+        type: "example",
+      },
+      {
+        title: "Spawn a subprocess",
+        href: "/examples/sandboxes_spawn_subprocess/",
+        type: "example",
+      },
+      {
+        title: "Serve a web framework",
+        href: "/examples/sandboxes_web_framework/",
+        type: "example",
+      },
+      {
+        title: "Privide SSH access to a sandbox",
+        href: "/examples/sandboxes_ssh_access/",
+        type: "example",
+      },
+      {
+        title: "Intereactive JavaScript REPL",
+        href: "/examples/sandboxes_javascript_repl/",
+        type: "example",
+      },
+      {
+        title: "Provide a VSCode instance in a sandbox",
+        href: "/examples/sandboxes_vscode_instance/",
+        type: "example",
+      },
+      {
+        title: "Use template literals with variable interpolation",
+        href: "/examples/sandboxes_template_literals/",
+        type: "example",
+      },
+      {
+        title: "Error handling",
+        href: "/examples/sandboxes_error_handling/",
+        type: "example",
+      },
+      {
+        title: "Error handling with custom error classes",
+        href: "/examples/sandboxes_custom_error_classes/",
+        type: "example",
+      },
+      {
+        title: "Command cancellation",
+        href: "/examples/sandboxes_command_cancellation/",
+        type: "example",
+      },
+      {
+        title: "Access string and binary output",
+        href: "/examples/sandboxes_access_output/",
+        type: "example",
+      },
+      {
+        title: "Set and get environment variables",
+        href: "/examples/sandboxes_environment_variables/",
+        type: "example",
+      },
+      {
+        title: "Stream output to a local file",
+        href: "/examples/sandboxes_stream_output/",
+        type: "example",
+      },
+      {
+        title: "Upload files and directories to a sandbox",
+        href: "/examples/sandboxes_upload_files/",
+        type: "example",
+      },
+      {
+        title: "Control sandbox lifetime",
+        href: "/examples/sandboxes_lifetime_control/",
+        type: "example",
+      },
+      {
+        title: "Configure sandbox memory",
+        href: "/examples/sandboxes_memory/",
+        type: "example",
+      },
+    ],
+  },
   {
     title: "Testing",
     items: [

examples/_data.ts

@@ -0,0 +1,24 @@
+---
+title: "Access string and binary output"
+description: "Learn how to access string and binary output from commands in a sandbox."
+url: /examples/sandboxes_access_output/
+layout: sandbox-example.tsx
+---
+
+You can access string and binary output from commands in a sandbox.
+
+```ts
+import { Sandbox } from "@deno/sandbox";
+
+await using sandbox = await Sandbox.create();
+
+// Get both string and binary data
+const result = await sandbox.sh`cat binary-file.png`
+  .stdout("piped");
+console.log("Binary length:", result.stdout!.length);
+console.log("Text length:", result.stdoutText!.length);
+
+// Use the binary data
+import fs from "node:fs";
+fs.writeFileSync("output.png", result.stdout!);
+```

examples/sandboxes/access_output.md

@@ -0,0 +1,30 @@
+---
+title: "Command cancellation"
+description: "Learn how to cancel commands in a sandbox."
+url: /examples/sandboxes_command_cancellation/
+layout: sandbox-example.tsx
+---
+
+You can cancel commands in a sandbox using the `KillController` class.
+
+```ts
+import { KillController, Sandbox } from "@deno/sandbox";
+
+await using sandbox = await Sandbox.create();
+
+// Start a long-running command
+const controller = new KillController();
+const cmd = sandbox.sh`sleep 30`.signal(controller.signal);
+const promise = cmd.text();
+
+// Cancel after 2 seconds
+setTimeout(() => {
+  controller.kill(); // Kill the process
+}, 2000);
+
+try {
+  await promise;
+} catch (error) {
+  console.log("Command was cancelled:", error);
+}
+```