Initialbook

Author: udzura

.gitignore

@@ -0,0 +1 @@
+book

README.md

@@ -0,0 +1,2 @@
+# uzumibi-book-draft
+Draft file for uzumibi book version 1

book.toml

@@ -0,0 +1,4 @@
+[book]
+title = "Introduction to Uzumibi"
+authors = ["Uchio Kondo"]
+language = "en"

src/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Kondo Uchio
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

src/SUMMARY.md

@@ -0,0 +1,23 @@
+# Summary
+
+- [Introduction](./ch01/index.md)
+  - [What is mruby/edge](./ch01/mruby_edge.md)
+  - [What is Uzumibi](./ch01/uzumibi.md)
+- [Project Setup and Hello World](./ch02/index.md)
+  - [Installing uzumibi-cli](./ch02/install_cli.md)
+  - [Creating a Project](./ch02/create_project.md)
+  - [Implementing Hello World](./ch02/hello_world.md)
+  - [Starting the Dev Server](./ch02/dev_server.md)
+  - [Deployment](./ch02/deploy.md)
+- [Uzumibi and External Services](./ch03/index.md)
+- [Calling External APIs with Fetch](./ch04/index.md)
+- [Saving Memos with Durable Object](./ch05/index.md)
+- [Communicating with Cloudflare Queue](./ch06/index.md)
+  - [Queue Use Cases](./ch06/use_cases.md)
+  - [Queue Architecture and Setup](./ch06/overview.md)
+  - [Publisher Implementation](./ch06/publisher.md)
+  - [Consumer Implementation](./ch06/consumer.md)
+- [Appendix](./ch07/index.md)
+  - [Supported Platforms](./ch07/platforms.md)
+  - [Current Limitations](./ch07/limitations.md)
+- [References](./references.md)

src/ch01/index.md

@@ -0,0 +1,3 @@
+# Introduction
+
+Before discussing Uzumibi, let's first organize the concepts around mruby/edge, the mruby implementation that serves as Uzumibi's foundation. After that, we'll provide an overview of Uzumibi itself.

src/ch01/mruby_edge.md

@@ -0,0 +1,69 @@
+# What is mruby/edge
+
+mruby/edge is a lightweight mruby implementation specialized for WebAssembly (Wasm) environments. It leverages the bytecode specification of mruby, a lightweight Ruby VM, and was developed with the goal of running efficiently in edge computing and serverless environments.
+
+## What is mruby
+
+[mruby](https://mruby.org/) is a lightweight implementation of the Ruby language designed to run in embedded environments and resource-constrained systems. It is primarily developed under the leadership of Yukihiro Matsumoto, the creator of Ruby. Compared to CRuby (the standard Ruby implementation), mruby has a smaller binary size and lower memory usage, making it suitable for embedding in various environments such as IoT devices and game engines.
+
+<https://mruby.org/>
+
+Recently, other implementations compatible with mruby's bytecode have been developed and are gaining attention, such as the even smaller [mruby/c](https://github.com/mrubyc/mrubyc) and [PicoRuby](https://picoruby.org/), which offers a more practical embedded ecosystem.
+
+## Features of mruby/edge
+
+mruby/edge is a re-implementation of the VM that executes mruby bytecode (`.mrb` files) written in Rust. It has the following features:
+
+- **First-class WebAssembly support**: Designed to generate portable Wasm code. Currently supports compilation to `wasm32-unknown-unknown` and `wasm32-wasip1` targets, running on browsers, Wasmtime, Cloudflare Workers, Fastly Compute@Edge, and various other WASM runtimes.
+- **Rust implementation**: Since the VM is written in Rust, it offers high memory safety and smooth compilation to Wasm.
+- **mruby 3.2.0 compatibility**: Supports opcodes from mruby 3.2.0 through 3.4.0, enabling use of basic Ruby syntax and data types.
+- **SharedMemory**: Provides a mechanism for efficient data exchange with the host environment (JavaScript, etc.) by utilizing Wasm's linear memory.
+
+## From mruby Code to WASM
+
+The flow of converting Ruby code to Wasm with mruby/edge is as follows:
+
+```
+Ruby source code (.rb)
+    ↓ Compile with mruby compiler (mrbc, mruby-compiler2, etc.)
+mruby bytecode (.mrb)
+    ↓ Embed in Rust binary
+    ↓ Compile to Wasm with cargo
+Wasm module (.wasm)
+```
+
+This Wasm module can run in browsers. Additionally, by executing it on edge platforms such as Cloudflare Workers or Fastly, applications written in Ruby can be run at the edge.
+
+It is also possible to embed mruby-compiler2 into Rust to directly execute Ruby scripts with mruby/edge. You can try it out on the [Playground](https://mrubyedge.github.io/playground/).
+
+<https://mrubyedge.github.io/playground/>
+
+## Supported Ruby Features
+
+The following Ruby language features are supported in mruby/edge:
+
+- Basic operations (arithmetic, comparison)
+- Conditional branching (`if/elsif/else`, `case/when`)
+- Method definition and recursive calls
+- Class definition and instance variables
+- `attr_reader` declarations
+- Global variables (`$var`)
+- Arrays (`Array`), Hashes (`Hash`), Strings (`String`)
+- Range objects (`Range`)
+- Blocks and iterators
+- Exception handling (`raise`/`rescue`)
+- String `unpack`/`pack` (binary data processing)
+
+The specific supported methods can be checked in the [`COVERAGE.md`](https://github.com/mrubyedge/mrubyedge/blob/v1.1.10/mrubyedge/COVERAGE.md) file. It may also be useful to have AI reference this file.
+
+Additionally, the following libraries are available as mrubyedge gems:
+
+- `mruby-random`
+- `mruby-regexp`
+- `mruby-math`
+- `mruby-serde-json`
+- `mruby-time`
+
+## Summary of mruby/edge
+
+mruby/edge plays a crucial role as the foundation of the Uzumibi framework, enabling Ruby-written web application logic to run in edge environments.

src/ch01/uzumibi.md

@@ -0,0 +1,108 @@
+# What is Uzumibi
+
+Uzumibi is a lightweight framework for building web applications in Ruby on edge computing platforms, built on top of mruby/edge.
+
+The name "Uzumibi" is inspired by the popular edge framework [Hono](https://hono.dev/). Hono + Embedded (埋まっている / "buried") = Uzumibi (うずみび / "buried embers") 😅
+
+## Overview of Uzumibi
+
+Uzumibi is a web application framework that allows you to define routing using a Sinatra-like DSL. You can write applications that handle HTTP requests with Ruby code like the following:
+
+```ruby
+class App < Uzumibi::Router
+  get "/" do |req, res|
+    res.status_code = 200
+    res.headers = {
+      "content-type" => "text/plain",
+      "x-powered-by" => "#{RUBY_ENGINE} #{RUBY_VERSION}"
+    }
+    res.body = "It works!\n"
+    res
+  end
+
+  get "/greet/to/:name" do |req, res|
+    res.status_code = 200
+    res.headers = {
+      "content-type" => "text/plain",
+    }
+    res.body = "Hello, #{req.params[:name]}!!\n"
+    res
+  end
+end
+
+$APP = App.new
+```
+
+## How It Works
+
+Uzumibi applications operate in a two-layer architecture:
+
+1. **Wasm layer (Rust + mruby/edge)**: Ruby code is compiled into mruby bytecode and embedded in a Wasm module. Request processing is handled by Ruby code running on the mruby/edge VM.
+2. **Platform layer (JavaScript / Rust)**: Glue code that bridges the edge platform's native APIs with the Wasm module. It handles binary serialization of HTTP requests/responses.
+
+The request flow looks like this:
+
+```
+Client
+    → Edge platform
+    → Glue code (JS/Rust) serializes request to binary
+    → Ruby code executes on mruby/edge VM inside WASM module
+    → Response is deserialized from binary
+    → Response returned to client
+```
+
+## Routing
+
+Uzumibi's router supports the following HTTP methods:
+
+- `get`
+- `post`
+- `put`
+- `delete`
+- `head`
+- `options`
+
+URL paths can include dynamic parameters (`:name`) and wildcards (`*`). Parameters are accessible via `req.params`, which is a Hash.
+
+```ruby
+# Dynamic parameter example
+get "/users/:id" do |req, res|
+  user_id = req.params[:id]
+  # ...
+end
+```
+
+In this book, we refer to the Ruby blocks defined with `get`, `post`, etc. as "route handlers".
+
+## Request Object
+
+The `req` object (`Uzumibi::Request`) passed to the route handler block holds the following information:
+
+- `req.method` - HTTP method (GET, POST, etc.)
+- `req.path` - Request path
+- `req.query` - Query string
+- `req.headers` - Request headers (Hash)
+- `req.body` - Request body
+- `req.params` - A Hash that integrates URL parameters, query parameters, and form data
+
+## Response Object
+
+The `res` object (`Uzumibi::Response`) is used to construct the response by setting the following properties:
+
+- `res.status_code` - HTTP status code (integer)
+- `res.headers` - Response headers (Hash)
+- `res.body` - Response body (string)
+
+The route handler block must always return the `res` object.
+
+## External Service Integration
+
+Uzumibi also supports access to external services provided by edge platforms. On Cloudflare Workers, the following are available:
+
+- **`Uzumibi::Fetch`** - Call external HTTP APIs
+- **`Uzumibi::KV`** - Key-Value store using Durable Objects
+- **`Uzumibi::Queue`** - Asynchronous messaging with Cloudflare Queues
+
+These features are explained in detail in later chapters.
+
+> **Note:** As of March 14, 2026, external services are not available on platforms other than Cloudflare Workers. Support for other platforms will be added progressively. Pull requests are always welcome!

src/ch02/create_project.md

@@ -0,0 +1,116 @@
+# Creating a Project
+
+Use the `uzumibi new` command to create a project for Cloudflare Workers.
+
+## Generating the Project
+
+Create a project named `hello-uzumibi` with the following command:
+
+```bash
+uzumibi new --template cloudflare hello-uzumibi
+```
+
+Running this command will create a project directory and generate the necessary files:
+
+```
+Creating project 'hello-uzumibi'...
+  generate  hello-uzumibi/.gitignore
+  generate  hello-uzumibi/Cargo.toml
+  generate  hello-uzumibi/package.json
+  generate  hello-uzumibi/vitest.config.js
+  generate  hello-uzumibi/wrangler.jsonc
+  generate  hello-uzumibi/lib/app.rb
+  generate  hello-uzumibi/public/assets/index.html
+  generate  hello-uzumibi/src/index.js
+  generate  hello-uzumibi/wasm-app/Cargo.toml
+  generate  hello-uzumibi/wasm-app/build.rs
+  generate  hello-uzumibi/wasm-app/src/lib.rs
+
+✓ Successfully created project from template 'cloudflare'
+  Run 'cd hello-uzumibi' to get started!
+```
+
+## Project Directory Structure
+
+The generated project has the following structure:
+
+```
+hello-uzumibi/
+├── Cargo.toml          # Rust workspace configuration
+├── package.json        # Node.js dependencies and scripts
+├── wrangler.jsonc      # Wrangler (Cloudflare Workers CLI) configuration
+├── lib/
+│   └── app.rb          # Ruby application code (main)
+├── public/
+│   └── assets/...      # Static assets (HTML, CSS, images, etc.)
+├── src/
+│   └── index.js        # JavaScript glue code (entry point)
+└── wasm-app/
+    ├── Cargo.toml      # WASM crate configuration
+    ├── build.rs        # Build script (compiles Ruby code)
+    ├── src/
+    │   └── lib.rs      # Rust code for the WASM module
+    └── .cargo/
+        └── config.toml # Cargo target settings (may not exist)
+```
+
+## Role of Each File
+
+### `lib/app.rb`
+
+**This is the main file that developers edit.** You write Uzumibi's routing and request handling logic in Ruby here.
+
+### `src/index.js`
+
+The entry point for Cloudflare Workers. It receives HTTP requests, serializes them to binary format and passes them to the WASM module, then deserializes the response and returns it to the client. Normally, you don't need to edit this file.
+
+### `wasm-app/`
+
+A Rust crate for compiling Ruby code into mruby bytecode and packaging it as a WASM module. Normally, you don't need to edit these files.
+
+- `build.rs` contains configuration to compile `lib/app.rb` into mruby bytecode (`.mrb`) at build time.
+- `src/lib.rs` handles mruby/edge VM initialization and export function definitions.
+
+### `wrangler.jsonc`
+
+The Cloudflare Workers configuration file. It contains the application name, static asset settings, and more.
+
+```jsonc
+{
+    "name": "hello-uzumibi",
+    "main": "src/index.js",
+    "compatibility_date": "2025-12-30",
+    "assets": {
+        "directory": "./public",
+        "binding": "ASSETS"
+    }
+}
+```
+
+### `package.json`
+
+Defines npm/pnpm scripts and dependencies.
+
+```json
+{
+    "scripts": {
+        "deploy": "wrangler deploy",
+        "dev": "cargo build --package hello-uzumibi --target wasm32-unknown-unknown --release && cp -v -f target/wasm32-unknown-unknown/release/hello_uzumibi.wasm src/ && wrangler dev",
+        "start": "wrangler dev",
+        "test": "vitest"
+    }
+}
+```
+
+The `dev` script performs both the Rust build (WASM compilation) and Wrangler dev server startup in one step.
+
+## Installing Dependencies
+
+Navigate to the project directory and install the Node.js dependencies:
+
+```bash
+cd hello-uzumibi
+pnpm install
+```
+
+This installs development tools including Wrangler locally within the project.