Documentation improvement - 1

docs/getting-started/applications/_category_.yml → docs/applications/_category_.yml

@@ -1,5 +1,5 @@
 label: "Applications"
-position: 1
+position: 3
 link:
   type: generated-index
   title: "Applications"

docs/getting-started/applications/go.md → docs/applications/go.md

@@ -4,27 +4,27 @@
 
 Go 1.21, due to be released in August 2023, will be able to natively compile Go applications to WebAssembly.
 
-```console
-$ GOOS=wasip1 GOARCH=wasm go build ...
+```bash
+GOOS=wasip1 GOARCH=wasm go build ...
 ```
 
 Since Go 1.21 has not been released yet, you can use [`gotip`](https://pkg.go.dev/golang.org/dl/gotip) to test these features before release:
 
-```console
-$ go install golang.org/dl/gotip@latest
-$ gotip download
+```bash
+go install golang.org/dl/gotip@latest
+gotip download
 ```
 
-```console
-$ GOOS=wasip1 GOARCH=wasm gotip build ...
+```bash
+GOOS=wasip1 GOARCH=wasm gotip build ...
 ```
 
 ## Compiling your application
 
 Instead of using `go build`, use:
 
-```console
-$ GOOS=wasip1 GOARCH=wasm gotip build -o app.wasm <path/to/main/pkg>
+```
+GOOS=wasip1 GOARCH=wasm gotip build -o app.wasm <path/to/main/pkg>
 ```
 
 This will build a WebAssembly module that can be run with Timecraft.
@@ -33,15 +33,15 @@ This will build a WebAssembly module that can be run with Timecraft.
 
 To run your application:
 
-```console
-$ timecraft run app.wasm
+```bash
+timecraft run app.wasm
 ```
 
 Command-line arguments can be specified after the WebAssembly module. To prevent
 Timecraft from interpreting command-line options for the application, use:
 
-```console
-$ timecraft run -- app.wasm arg1 arg2 ...
+```bash
+timecraft run -- app.wasm arg1 arg2 ...
 ```
 
 Note that environment variables passed to Timecraft are automatically passed to the

docs/getting-started/applications/python.md → docs/applications/python.md

@@ -11,7 +11,7 @@ create servers and connect to databases. We intend to upstream our patches at so
 
 We provide a pre-compiled Python interpreter and patched standard library. You can download them by running
 
-```
+```bash
 curl -fsSL https://timecraft.s3.amazonaws.com/python/main/python.wasm -o python.wasm
 curl -fsSL https://timecraft.s3.amazonaws.com/python/main/python311.zip -o python311.zip
 ```
@@ -25,9 +25,9 @@ To build Python from scratch, see the instructions in the
 
 It's recommended that you install your Python dependencies in a virtualenv:
 
-```console
-$ python3 -m venv env
-$ source ./env/bin/activate
+```bash
+python3 -m venv env
+source ./env/bin/activate
 (env) $ pip install -r /path/to/requirements.txt
 ```
 
@@ -40,13 +40,13 @@ Assuming both the interpreter (`python.wasm`) and standard library (`python311.z
 are located in the current directory, you can pass this information to the
 interpreter like so:
 
-```
-$ export PYTHONHOME=env
-$ export PYTHONPATH=python311.zip:$PYTHONHOME
+```bash
+export PYTHONHOME=env
+export PYTHONPATH=python311.zip:$PYTHONHOME
 ```
 
 You can now run your application:
 
-```
-$ timecraft run python.wasm main.py
+```bash
+timecraft run python.wasm main.py
 ```

docs/architecture/_category_.yml

@@ -0,0 +1,5 @@
+label: "Architecture"
+position: 4
+link:
+  type: generated-index
+  title: "Architecture"

docs/networking/htls.md → docs/architecture/htls.md

@@ -17,7 +17,7 @@ abilities. Server-side and further configuration options will be supported as
 needed. [Send a pull request!][htls-code]
 
 [htls-code]: https://github.com/stealthrocket/timecraft
-[tracing]: /using-timecraft/execution-tracing.md
+[tracing]: /guides/execution-tracing.md
 
 At a very high level, hTLS works by setting a special option on a socket. How
 to set that option is described in the [Usage](#usage) section below. Socket
@@ -92,7 +92,7 @@ with socket.create_connection((hostname, 443)) as sock:
         print(buf[:nbytes])
 ```
 
-[python]: /getting-started/applications/python
+[python]: /applications/python
 [requests]: https://requests.readthedocs.io/en/latest/
 
 ### C

docs/architecture/log.md

@@ -0,0 +1,3 @@
+# The Log
+
+Coming soon.

docs/getting-started/architecture.md

@@ -0,0 +1,62 @@
+---
+sidebar_position: 1
+---
+
+# Architecture
+
+Timecraft is an application runtime leverage WebAssembly as main sandboxing system. On top of it, Timecraft implements a networking and filesystem sandbox allowing
+operators to get full control of their applications' interactions with the rest of the world.
+
+
+:::info
+We are activelly working on bringing a native sandboxing system to Timecraft. While we believe that WebAssembly is the future of cloud computing and distributed systems, we might want to leverage your existing development workflow while still benefit from the Timecraft features. The native sandbox will be based on cAdvisor.
+:::
+
+
+## Timecraft internals
+
+Internally, Timecraft is composed of the following:
+
+- A WebAssembly runtime 
+- A decentralized scheduler
+- A log of execution
+
+### WebAssembly runtime
+
+Timecraft leverags Wazero for its WebAssembly runtime and enhances it with a couple of goodies.
+
+The WASI layer implements a [complete, non-blocking, network stack](https://github.com/stealthrocket/wasi-go/blob/main/imports/wasi_snapshot_preview1/wasmedge.go) based on the WasmEdge API, allowing developers to run a full application in WASM. While we are currently using the WasmEdge API, we are also looking at implementing [WASIX](http://wasix.org/) to provide wider compatibility with the WebAssembly ecosystem.
+
+The Timecraft WASI layer is currently fully compatible with Go 1.21 (to be released later this month) and Python 3.11. Note that Python Asyncio is also supported.
+
+
+### Decentralized scheduler
+
+Timecraft ships with a built-in decentralized orchestrator enabling durable execution at scale. The orchestrator is still in active development but fully functional.
+Developers can programatically create graph of execution of actors, Timecraft will ensure those actors go to completion not matter the infrastructure event (instance restart, network partitions, etc).
+
+The interaction with the scheduler goes through the [Timecraft SDK](https://github.com/stealthrocket/timecraft/tree/main/sdk) currently available for Golang and Python. More languages will be supported as we move forward.
+
+:::info
+More details about the durable execution can be found in the dedicated guides: [Durable execution](/guides/durable-execution).
+:::
+
+### Log of execution
+
+Each Timecraft instance automatically record the entire execution of all application and actors it schedules. Coupled with the WebAssembly determinism, [The Log](/architecture/log) enables the Time Machine capabilities of the system:
+- Deterministic simulator
+- Profiling of past executions
+- Interactive debugging (coming soon)
+- Telemetry injection / Execution rehydratation (coming soon)
+
+# Time Machine
+
+The Time Machine is a core primitive of Timecraft that brings a new step function in scaling the development and operation of distributed systems. Because the recording happens at the bottom-most level of interaction between the host runtime and the guest applications, it scales with the addition of new capabilities. For example, recording all network connections at the socket layer means that we can track the network messages exchanged in any protocol. Applications using protocols that cannot yet generate high-level observability can still be executed and recorded, and capabilities can be added later on to extract value from the records.
+
+Decoupling the recording from the high-level machinery is the architectural model that brings scalability. Instead of systems having to implement their instrumentation, the separation of concerns offered by the low-level recording capability provides a much more powerful model where extracting context from the record does not require modification of the application code, and can happen after the fact on records of past executions.
+
+Because the capture happens on the critical path of the guest application, it must be fast. The write path of the time machine must be optimized to have the lowest possible cost. The data captured is first buffered in memory, then sent to local storage and can be synced asynchronously to an object store like S3 for long-term durability at an affordable cost.
+
+Over time, we anticipate that the development of most operational capabilities could be built on top of Time Machines: time travel debugging through layers of services, high-level telemetry, or deterministic simulations could all be derived from the records captured from the execution of guest applications on the runtime. The possibilities span far beyond software operations and could even reach the realm of data analytics: data lakes of application records where asynchronous batch processing pipelines create views tailored to provide insight into all aspects of the products built on top of those distributed systems.
+
+One of the main challenges of those Time Machines is facilitating access to the scale of records that it produces. Even with effective compression to minimize the storage footprint, they can geneate very large volumes of information. Developing solutions to efficiently access the gold mine of data captured in the logs is one of the responsibilities that Timecraft can fulfill on behalf of the applications it runs.

docs/getting-started/configuration.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 3
 ---
 # Configuring Timecraft
 
@@ -9,12 +9,12 @@ Timecraft directory and configuration file are created on demand.
 
 To view the current Timecraft configuration, run:
 
-```console
-$ timecraft config
+```bash
+timecraft config
 ```
 
 To edit the Timecraft configuration with your `$EDITOR`, run:
 
-```console
-$ timecraft config --edit
+```bash
+timecraft config --edit
 ```

docs/getting-started/installation.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 1
+sidebar_position: 2
 ---
 # Installing Timecraft
 
@@ -13,14 +13,14 @@ Timecraft requires [Go](https://go.dev/).
 
 macOS users using [homebrew](https://brew.sh/) can install Go using:
 
-```console
-$ brew install go
+```bash
+brew install go
 ```
 
 Ubuntu users can install Go with:
 
-```console
-$ sudo apt install golang
+```bash
+sudo apt install golang
 ```
 
 For other Linux systems, please see the [Go Releases](https://go.dev/dl/) page for installation instructions.
@@ -29,15 +29,15 @@ For other Linux systems, please see the [Go Releases](https://go.dev/dl/) page f
 
 To install Timecraft, run:
 
-```console
-$ go install github.com/stealthrocket/timecraft@latest
+```bash
+go install github.com/stealthrocket/timecraft@latest
 ```
 
 Timecraft should now be available. To check that installation was successful,
 run:
 
-```console
-$ timecraft help
+```bash
+timecraft help
 ```
 
 ## Installation Issues
@@ -47,12 +47,12 @@ $ timecraft help
 If the `timecraft` command cannot be found, make sure `$GOPATH/bin` is in
 your search path:
 
-```console
+```bash
 export PATH="$GOPATH/bin:$PATH"
 ```
 
 If `$GOPATH` has not been set, try:
 
-```
-$ go env | grep GOPATH
+```bash
+go env | grep GOPATH
 ```

docs/guides/_category_.yml

@@ -0,0 +1,5 @@
+label: "Guides"
+position: 3
+link:
+  type: generated-index
+  title: "Guides"

docs/using-timecraft/task-orchestration.md → docs/guides/durable-execution.md

@@ -1,4 +1,4 @@
-# Task orchestration
+# Durable execution
 
 Timecraft includes a technical preview of a task orchestration feature.
 

docs/using-timecraft/execution-tracing.md → docs/guides/execution-tracing.md

@@ -7,17 +7,17 @@ during execution, they are generated after the fact.
 
 To show a trace of [WASI](https://wasi.dev/) system calls made by the WebAssembly module, use:
 
-```console
-$ timecraft run --trace <MODULE>
+```bash
+timecraft run --trace <MODULE>
 ```
 
 This is similar to the [`strace`](https://man7.org/linux/man-pages/man1/strace.1.html) tool
 on Linux.
 
 To show a trace of WASI system calls made by a process that was running in the past, use:
 
-```console
-$ timecraft replay --trace <ID>
+```bash
+timecraft replay --trace <ID>
 ```
 
 ## Network Tracing
@@ -26,15 +26,15 @@ Timecraft can trace network activity.
 
 Here's an example application that makes an HTTP request:
 
-```
+```bash
 $ timecraft run testdata/go/get.wasm https://eo3qh2ncelpc9q0.m.pipedream.net
 b5770968-2ec7-4307-b613-61e8e9b2f9d2
 Hello, World!
 ```
 
 To trace low-level networking activity, use:
 
-```
+```bash
 $ timecraft trace network b5770968-2ec7-4307-b613-61e8e9b2f9d2
 2023/06/30 08:13:20.463329 TCP 172.16.0.0:49152 > 44.194.85.187:443: CONN EINPROGRESS
 2023/06/30 08:13:20.947931 TCP 172.16.0.0:49152 > 44.194.85.187:443: SEND OK 112
@@ -43,7 +43,7 @@ $ timecraft trace network b5770968-2ec7-4307-b613-61e8e9b2f9d2
 
 To show bytes transmitted, use `-v`:
 
-```
+```bash
 $ timecraft trace network -v b5770968-2ec7-4307-b613-61e8e9b2f9d2
 [23] 2023/06/30 08:13:20.463329 TCP 172.16.0.0:49152 > 44.194.85.187:443: CONN EINPROGRESS
 [40] 2023/06/30 08:13:20.947931 TCP 172.16.0.0:49152 > 44.194.85.187:443: SEND OK 112
@@ -76,14 +76,14 @@ $ timecraft trace network -v b5770968-2ec7-4307-b613-61e8e9b2f9d2
 
 To trace HTTP requests, use:
 
-```
+```bash
 $ timecraft trace request b5770968-2ec7-4307-b613-61e8e9b2f9d2
 2023/06/30 08:13:24.326929 HTTP 172.16.0.0:49152 > 44.194.85.187:443: GET / => 200 OK
 ```
 
 To show HTTP headers/body, use `-v`:
 
-```
+```bash
 $ timecraft trace request -v b5770968-2ec7-4307-b613-61e8e9b2f9d2
 2023/06/30 08:13:24.326929 HTTP 172.16.0.0:49152 > 44.194.85.187:443
 > GET / HTTP/1.1