From e4dd3893da31d99aa53e3b69c025ac3877e54eb0 Mon Sep 17 00:00:00 2001 From: Shadaj Laddad Date: Mon, 10 Feb 2025 17:01:00 -0800 Subject: [PATCH] docs: move DFIR playground to a sidebar item in the docs Fixes #1630 --- docs/docs/dfir/architecture/_category_.json | 2 +- docs/docs/dfir/concepts/_category_.json | 2 +- docs/docs/dfir/ecosystem.md | 2 +- docs/docs/dfir/lattices_crate/_category_.json | 2 +- docs/docs/dfir/playground.mdx | 14 + docs/docs/dfir/syntax/_category_.json | 2 +- docs/docusaurus.config.js | 13 +- docs/src/{pages => components}/playground.js | 324 +++++++++++------- .../playground.module.css | 0 9 files changed, 214 insertions(+), 147 deletions(-) create mode 100644 docs/docs/dfir/playground.mdx rename docs/src/{pages => components}/playground.js (54%) rename docs/src/{pages => components}/playground.module.css (100%) diff --git a/docs/docs/dfir/architecture/_category_.json b/docs/docs/dfir/architecture/_category_.json index 46438dff155b..17ca09ee0ab5 100644 --- a/docs/docs/dfir/architecture/_category_.json +++ b/docs/docs/dfir/architecture/_category_.json @@ -1,6 +1,6 @@ { "label": "Architecture", - "position": 6, + "position": 7, "link": { "type": "doc", "id": "dfir/architecture/index" diff --git a/docs/docs/dfir/concepts/_category_.json b/docs/docs/dfir/concepts/_category_.json index bd583e45a632..e7206d53a530 100644 --- a/docs/docs/dfir/concepts/_category_.json +++ b/docs/docs/dfir/concepts/_category_.json @@ -1,6 +1,6 @@ { "label": "Concepts", - "position": 5, + "position": 6, "link": { "type": "doc", "id": "dfir/concepts/index" diff --git a/docs/docs/dfir/ecosystem.md b/docs/docs/dfir/ecosystem.md index 0f3a4ab8d2ed..a08cc598e660 100644 --- a/docs/docs/dfir/ecosystem.md +++ b/docs/docs/dfir/ecosystem.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 --- # The Hydro Ecosystem diff --git a/docs/docs/dfir/lattices_crate/_category_.json b/docs/docs/dfir/lattices_crate/_category_.json index 925f9dc81248..2437f8b575a9 100644 --- a/docs/docs/dfir/lattices_crate/_category_.json +++ b/docs/docs/dfir/lattices_crate/_category_.json @@ -1,6 +1,6 @@ { "label": "The Lattices Crate", - "position": 6, + "position": 8, "link": { "type": "doc", "id": "dfir/lattices_crate/index" diff --git a/docs/docs/dfir/playground.mdx b/docs/docs/dfir/playground.mdx new file mode 100644 index 000000000000..acf9567bf196 --- /dev/null +++ b/docs/docs/dfir/playground.mdx @@ -0,0 +1,14 @@ +--- +title: DFIR Playground +sidebar_position: 3 +--- + +import { DfirSurfaceDemo, DatalogDemo } from '@site/src/components/playground'; + +In these interactive editors, you can experiment with the DFIR compiler by running it in your browser (through WebAssembly)! Try selecting one of the templates or edit the code yourself to see how DFIR logic is compiled into a dataflow graph and executable Rust. + +## DFIR + + +## Datalog + diff --git a/docs/docs/dfir/syntax/_category_.json b/docs/docs/dfir/syntax/_category_.json index 1ecc2d9a6213..027e9f97aace 100644 --- a/docs/docs/dfir/syntax/_category_.json +++ b/docs/docs/dfir/syntax/_category_.json @@ -1,6 +1,6 @@ { "label": "Syntax", - "position": 3, + "position": 4, "link": { "type": "doc", "id": "dfir/syntax/index" diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index ebb7cbaca047..2a150d97ff62 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -125,22 +125,17 @@ const config = { sidebarId: "deploySidebar", label: "Hydro Deploy", }, - { - href: "pathname:///rustdoc/hydro_lang/", - label: "Rustdoc", - }, { type: "docSidebar", sidebarId: "dfirSidebar", label: "DFIR", }, + { + href: "pathname:///rustdoc/hydro_lang/", + label: "Rustdoc", + }, ], }, - { - to: "/playground", - position: "left", - label: "Playground", - }, { to: "/research", position: "left", diff --git a/docs/src/pages/playground.js b/docs/src/components/playground.js similarity index 54% rename from docs/src/pages/playground.js rename to docs/src/components/playground.js index e3b2bf951ca9..f4c8d4402c89 100644 --- a/docs/src/pages/playground.js +++ b/docs/src/components/playground.js @@ -1,11 +1,10 @@ -import React, { useEffect, useState } from 'react'; -import Layout from '@theme/Layout'; +import React, { useEffect, useState } from "react"; import Editor from "@monaco-editor/react"; -import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment'; +import ExecutionEnvironment from "@docusaurus/ExecutionEnvironment"; -import siteConfig from '@generated/docusaurus.config'; +import siteConfig from "@generated/docusaurus.config"; import * as wasm from "website_playground/website_playground_bg.wasm"; import * as playgroundJS from "website_playground/website_playground_bg.js"; @@ -13,7 +12,7 @@ import * as playgroundJS from "website_playground/website_playground_bg.js"; let compile_DFIR = null; let compile_datalog = null; -if (siteConfig.customFields.LOAD_PLAYGROUND === '1') { +if (siteConfig.customFields.LOAD_PLAYGROUND === "1") { compile_DFIR = playgroundJS.compile_dfir; compile_datalog = playgroundJS.compile_datalog; @@ -21,10 +20,10 @@ if (siteConfig.customFields.LOAD_PLAYGROUND === '1') { playgroundJS.__wbg_set_wasm(wasm); } else { const wasmUri = require("website_playground/website_playground_bg.wasm"); - const wasmBuffer = Buffer.from(wasmUri.split(",")[1], 'base64'); + const wasmBuffer = Buffer.from(wasmUri.split(",")[1], "base64"); const wasm = new WebAssembly.Module(wasmBuffer); const instance = new WebAssembly.Instance(wasm, { - "./website_playground_bg.js": require("website_playground/website_playground_bg.js") + "./website_playground_bg.js": require("website_playground/website_playground_bg.js"), }); playgroundJS.__wbg_set_wasm(instance.exports); } @@ -37,7 +36,7 @@ import mermaid from "mermaid"; import styles from "./playground.module.css"; function MermaidGraph({ id, source }) { - const [svg, setSvg] = useState({ __html: 'Loading Mermaid graph...' }); + const [svg, setSvg] = useState({ __html: "Loading Mermaid graph..." }); useEffect(() => { mermaid.render(id, source).then(({ svg }) => { setSvg({ @@ -46,17 +45,23 @@ function MermaidGraph({ id, source }) { }); }, [source]); - return
; + return ( +
+ ); } const DfirExamples = { - "Simplest": `\ + Simplest: `\ // https://hydro.run/docs/dfir/quickstart/example_1_simplest source_iter(0..10) -> for_each(|n| println!("Hello {}", n));`, - "Simple": `\ + Simple: `\ // https://hydro.run/docs/dfir/quickstart/example_2_simple source_iter(0..10) -> map(|n| n * n) @@ -161,11 +166,11 @@ all_vertices[0] -> [pos]unreached_vertices; reached_vertices[1] -> [neg]unreached_vertices; // the output all_vertices[1] -> unique() -> for_each(|v| println!("Received vertex: {}", v)); -unreached_vertices -> for_each(|v| println!("unreached_vertices vertex: {}", v));` +unreached_vertices -> for_each(|v| println!("unreached_vertices vertex: {}", v));`, }; const datalogExamples = { - "Simplest": `\ + Simplest: `\ .input foo \`null()\` .output bar \`null()\` bar(x) :- foo(x)`, @@ -174,19 +179,36 @@ bar(x) :- foo(x)`, .input seed_reachable \`null()\` .output reachable \`null()\` reachable(x) :- seed_reachable(x) -reachable(y) :- reachable(x), edges(x, y)` +reachable(y) :- reachable(x), edges(x, y)`, }; export function DfirSurfaceDemo() { - return + return ( + + ); } export function DatalogDemo() { - return + return ( + + ); } export function EditorDemo({ compileFn, examples, mermaidId }) { - if (siteConfig.customFields.LOAD_PLAYGROUND !== '1') { - return
Please set LOAD_PLAYGROUND environment variable to 1 to enable the playground.
; + if (siteConfig.customFields.LOAD_PLAYGROUND !== "1") { + return ( +
+ Please set LOAD_PLAYGROUND environment variable to 1 to enable the + playground. +
+ ); } const [program, setProgram] = useState(Object.values(examples)[0]); @@ -210,129 +232,165 @@ export function EditorDemo({ compileFn, examples, mermaidId }) { return true; }; - const { output, diagnostics } = (compileFn)(program, ...Object.values(writeGraphConfig)); + const { output, diagnostics } = compileFn( + program, + ...Object.values(writeGraphConfig), + ); const numberOfLines = program.split("\n").length; useEffect(() => { if (editorAndMonaco) { const { editor, monaco } = editorAndMonaco; - monaco.editor.setModelMarkers(editor.getModel(), "dfir_rs", diagnostics.map(d => { - return { - startLineNumber: d.span.start.line, - startColumn: d.span.start.column + 1, - endLineNumber: d.span.end ? d.span.end.line : numberOfLines + 1, - endColumn: d.span.end ? d.span.end.column + 1 : 0, - message: d.message, - severity: d.is_error ? monaco.MarkerSeverity.Error : monaco.MarkerSeverity.Warning - }; - })); + monaco.editor.setModelMarkers( + editor.getModel(), + "dfir_rs", + diagnostics.map((d) => { + return { + startLineNumber: d.span.start.line, + startColumn: d.span.start.column + 1, + endLineNumber: d.span.end ? d.span.end.line : numberOfLines + 1, + endColumn: d.span.end ? d.span.end.column + 1 : 0, + message: d.message, + severity: d.is_error + ? monaco.MarkerSeverity.Error + : monaco.MarkerSeverity.Warning, + }; + }), + ); } }, [editorAndMonaco, numberOfLines, diagnostics]); - return
-
- Template: - { - setProgram(value); - }} - onMount={(editor, monaco) => { - setEditorAndMonaco({ editor, monaco }); - }} - /> -
-
-
- setShowingMermaid(true)} role="button">Graph -  /  - setShowingMermaid(false)} role="button">Compiled Rust + return ( +
+
+ Template: + + { + setProgram(value); + }} + onMount={(editor, monaco) => { + setEditorAndMonaco({ editor, monaco }); + }} + />
- {(() => { - if (null == output) { - return
-

Failed to compile:

-
    {diagnostics.map(diag =>
  • {diag.is_error ? "Error" : "Warning"}: {diag.message} ({diag.span.start.line}:{diag.span.start.column})
  • )}
-
; - } - if (showingMermaid) { - return
- setShowGraphOpts(!showGraphOpts)}>… -
- +
+ ); + } + if (showingMermaid) { + return ( +
+ setShowGraphOpts(!showGraphOpts)} + > + … + +
+
    + {Object.keys(writeGraphConfig).map((name) => { + return ( +
  • + +
  • + ); + })} +
+
+ +
+ ); + } else { + return ( + + ); + } + })()} +
-
-} - -export default function Playground() { - return ( - -
-
-

Playground

-

In these interactive editors, you can experiment with the DFIR compiler by running it in your browser (through WebAssembly)! Try selecting one of the templates or edit the code yourself to see how DFIR logic is compiled into a dataflow graph and executable Rust.

-

DFIR

- -

Datalog

- -
-
-
); } diff --git a/docs/src/pages/playground.module.css b/docs/src/components/playground.module.css similarity index 100% rename from docs/src/pages/playground.module.css rename to docs/src/components/playground.module.css