tokra 0.0.1.pre.1 → 0.0.1.pre.2

data/doc/contributors/plan/002.md

@@ -0,0 +1,173 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Test Coverage Implementation Plan
+
+## Goal
+
+Ensure every line of `ext/` and `lib/` is covered by high-quality tests that would stand up to mutation testing. Tests should verify behavior, not just call code.
+
+## Current State
+
+| File | Lines | Current Tests | Coverage |
+|------|-------|---------------|----------|
+| `lib/tokra.rb` | 20 | 1 (version) | ~10% |
+| `lib/tokra/version.rb` | 13 | 1 | 100% |
+| `lib/tokra/native.rb` | 80 | 0 (docs only) | N/A |
+| `lib/tokra/rack/handler.rb` | 184 | 0 | 0% |
+| `ext/tokra/src/lib.rs` | 721 | 3 (invariants) | ~5% |
+
+## Test Strategy
+
+Following Alexander Tarlinder's principles from _Developer Testing_:
+- **Mutation-resistant**: Tests verify observable behavior, not implementation details
+- **Classicist for results**: State verification for handler responses
+- **Mockist for collaboration**: Spy on Proxy#respond calls to verify IPC flow
+- **Library tests as documentation**: Each test describes expected usage
+
+---
+
+## Proposed Changes
+
+### Unit Tests: Rack Handler
+
+#### [NEW] [test_rack_handler.rb](file:///Users/kerrick/Developer/tokra/test/test_rack_handler.rb)
+
+Tests for `Rack::Handler::Tokra`:
+
+1. **`.run` method behavior**
+   - Creates EventLoop, Proxy, Window, WebView
+   - Accepts options (title, width, height)
+   - Accepts invoke_handler for IPC
+   - Merges DEFAULT_OPTIONS correctly
+
+2. **`#call` method - core request handling**
+   - Translates HttpRequestEvent URI into Rack env
+   - Calls app.call with correct env hash
+   - Returns response via proxy.respond
+   - Handles empty paths ("/" default)
+
+3. **Redirect following (mutation-critical!)**
+   - Follows 301/302/303 redirects internally
+   - Respects MAX_REDIRECTS (10)
+   - Returns 508 on redirect loop
+   - Preserves Set-Cookie across redirects (PRG pattern)
+   - Converts POST to GET after redirect
+
+4. **`#build_env` private method**
+   - Sets all required Rack env keys
+   - Handles query strings
+   - Sets proper rack.* keys
+   - Injects HTTP_COOKIE when provided
+
+5. **Error handling**
+   - Returns proper error response for redirect overflow
+
+---
+
+### Unit Tests: Native Extension Events
+
+#### [NEW] [test_native_events.rb](file:///Users/kerrick/Developer/tokra/test/test_native_events.rb)
+
+1. **IpcEvent**
+   - `.new(message)` stores message
+   - `#message` returns the stored string
+
+2. **WakeUpEvent**
+   - `.new(payload)` stores payload
+   - `#payload` returns the stored string
+
+3. **WindowCloseEvent**
+   - `.new` creates instance (no args)
+
+4. **HttpRequestEvent**
+   - `.new(request_id, method, uri, body)` stores all fields
+   - `#request_id`, `#method`, `#uri`, `#body` return correct values
+
+5. **PageLoadEvent**
+   - `.new(event, url)` stores both
+   - `#event` returns "started" or "finished"
+   - `#url` returns the URL
+   - `#started?` returns true when event == "started"
+   - `#finished?` returns true when event == "finished"
+
+---
+
+### Unit Tests: Native Extension Core Types
+
+#### [MODIFY] [thread_safety_invariant_test.rb](file:///Users/kerrick/Developer/tokra/test/integration/thread_safety_invariant_test.rb)
+
+Add tests for:
+
+1. **EventLoop**
+   - `#create_proxy` returns Proxy before `#run`
+   - `#create_proxy` raises after `#run` consumed loop
+   - `#run` raises if called twice
+
+2. **Window**
+   - `#set_title` accepts string
+   - `#set_size` accepts width, height as floats
+   - `#id` returns unique identifier
+
+3. **WebView**
+   - `.new_with_protocol` registers tokra:// handler
+   - `#eval` executes JavaScript
+
+4. **Proxy**
+   - `#wake_up` accepts string payload
+   - `#respond` accepts request_id, status, headers, body
+   - Raises when event loop is closed
+
+---
+
+### Unit Tests: Entry Point & Error Class
+
+#### [MODIFY] [test_tokra.rb](file:///Users/kerrick/Developer/tokra/test/test_tokra.rb)
+
+1. **Module structure**
+   - `Tokra` is defined
+   - `Tokra::Native` is defined
+   - `Tokra::Error` is a StandardError subclass
+
+2. **VERSION format**
+   - Matches semantic versioning pattern
+
+---
+
+## Verification Plan
+
+### Automated Tests
+
+```bash
+bundle exec rake test
+```
+
+Expected outcome: All tests pass, no skips except display-server-dependent tests in CI.
+
+### Mutation Testing Validation
+
+The tests are designed to detect mutations in:
+- Redirect count threshold (MAX_REDIRECTS = 10)
+- Status code range checks ((300..399))
+- env hash key names
+- Method conversion in redirect (POST → GET)
+- Event type predicates (#started?, #finished?)
+
+---
+
+## Execution Order
+
+1. Create `test/test_rack_handler.rb` with mock-based tests
+2. Create `test/test_native_events.rb` for event types
+3. Expand `test/integration/thread_safety_invariant_test.rb`
+4. Update `test/test_tokra.rb` to remove skip
+5. Run full test suite and verify
+
+## Notes
+
+- Tests requiring a display server will skip in CI unless `DISPLAY` is set
+- Rack handler tests will use mock apps and mock proxies to avoid windowing
+- Event type tests can run headless (pure Ruby object instantiation via Rust)

data/doc/contributors/plan/003.md

@@ -0,0 +1,111 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Implementation Plan: HTTP Header Forwarding for CSRF/Cookie Support
+
+## Problem
+
+Rails form submissions fail with 422 CSRF error because cookies are not forwarded from WKWebView to Rails:
+
+1. WKWebView sends requests with `Cookie` header
+2. Tokra's Rust layer only extracts `method`, `uri`, `body` - **ignoring headers**
+3. Each Rails request appears as a new session → CSRF token mismatch
+
+## ADR Compatibility
+
+| ADR | Finding |
+|-----|---------|
+| **001** | ✅ Compatible. "Rust Layer (The Dumb Pipe)" - we're adding header passthrough, not logic |
+| **002** | ✅ **Explicitly expected**: Line 128 states "we must ensure set-cookie headers are respected by Wry's custom protocol implementation" |
+| **003** | ✅ Compatible. Build system unchanged |
+| **004** | ✅ Compatible. Builder pattern unchanged |
+
+## Tauri Reference
+
+Tauri's `protocol/tauri.rs:161` shows:
+```rust
+for (name, value) in request.headers() {
+    proxy_builder = proxy_builder.header(name, value);
+}
+```
+
+Tauri passes the full `http::Request` object (with headers) to handlers.
+
+---
+
+## Proposed Changes
+
+### Rust Layer
+
+#### [MODIFY] [user_event.rs](file:///Users/kerrick/Developer/tokra/ext/tokra/src/user_event.rs)
+
+Add `headers: Vec<(String, String)>` field to `UserEvent::HttpRequest` variant.
+
+#### [MODIFY] [webview.rs](file:///Users/kerrick/Developer/tokra/ext/tokra/src/webview.rs)
+
+Extract headers from `request`:
+```rust
+let headers: Vec<(String, String)> = request.headers()
+    .iter()
+    .map(|(name, value)| {
+        (name.to_string(), value.to_str().unwrap_or("").to_string())
+    })
+    .collect();
+```
+
+#### [MODIFY] [events.rs](file:///Users/kerrick/Developer/tokra/ext/tokra/src/events.rs)
+
+Add `headers` field to `RbHttpRequestEvent`:
+- Store as `Vec<(String, String)>`
+- Expose Ruby method `headers` returning array of 2-tuples
+
+#### [MODIFY] [event_loop.rs](file:///Users/kerrick/Developer/tokra/ext/tokra/src/event_loop.rs)
+
+Pass `headers` when creating `RbHttpRequestEvent::new()`.
+
+---
+
+### Ruby Layer
+
+#### [MODIFY] [handler.rb](file:///Users/kerrick/Developer/tokra/lib/tokra/rack/handler.rb)
+
+In `build_env`, convert headers to Rack format:
+```ruby
+# Add HTTP headers from the request (HTTP_* format for Rack)
+event.headers&.each do |(name, value)|
+  rack_name = "HTTP_#{name.upcase.tr('-', '_')}"
+  env[rack_name] = value
+end
+```
+
+---
+
+## Verification Plan
+
+### Automated Tests
+
+```bash
+# Run existing Rust unit tests (should still pass)
+cd /Users/kerrick/Developer/tokra
+cargo test
+```
+
+### Manual Verification
+
+1. Run the Rails example:
+```bash
+cd /Users/kerrick/Developer/tokra/examples/verify_rails_sqlite
+timeout 30 ruby tokra.rb 2>&1 || true
+```
+
+2. In the app window:
+   - Click "Add task" to navigate to `/todos/new`
+   - Fill in a task title and click "Create"
+   - **Expected**: Task is created and displayed (no 422 error)
+
+3. Verify server logs show:
+   - `[TOKRA]` logs include `Cookie` header being forwarded
+   - Rails logs show successful `POST /todos` with 302/303 redirect

data/examples/verify_hello_world/index.html

@@ -20,6 +20,19 @@ SPDX-License-Identifier: AGPL-3.0-or-later
       --text-muted: oklch(50% 0.015 250);
       --surface: oklch(98% 0.005 250);
       --accent: oklch(55% 0.18 150);
+      --code-bg: oklch(94% 0.01 250);
+      --status-bg: oklch(95% 0.04 150);
+    }
+
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --text: oklch(92% 0.01 250);
+        --text-muted: oklch(65% 0.015 250);
+        --surface: oklch(15% 0.02 250);
+        --accent: oklch(70% 0.18 150);
+        --code-bg: oklch(22% 0.02 250);
+        --status-bg: oklch(25% 0.06 150);
+      }
     }
 
     html {
@@ -60,7 +73,7 @@ SPDX-License-Identifier: AGPL-3.0-or-later
     code {
       font-family: ui-monospace, 'SF Mono', 'Cascadia Code', monospace;
       font-size: 0.9em;
-      background: oklch(94% 0.01 250);
+      background: var(--code-bg);
       padding: 0.15em 0.4em;
       border-radius: 4px;
     }
@@ -72,7 +85,7 @@ SPDX-License-Identifier: AGPL-3.0-or-later
       font-size: 0.85rem;
       font-weight: 600;
       color: var(--accent);
-      background: oklch(95% 0.04 150);
+      background: var(--status-bg);
       border-radius: 6px;
     }
   </style>

data/examples/verify_ping_pong/app.rb

@@ -126,7 +126,9 @@ Rack::Handler::Tokra.run(
   rack_app,
   title: "Tokra Ping-Pong",
   width: 500,
-  height: 600
+  height: 600,
+  # This acts like Tauri's invoke_handler, receiving IPC messages
+  invoke_handler: proc { |msg| LOGGER.info("Sent via IPC: #{msg}") }
 )
 
 LOGGER.info { "Event loop exited" }

data/examples/verify_ping_pong/public/styles.css

@@ -12,8 +12,35 @@ SPDX-License-Identifier: AGPL-3.0-or-later
   --border: oklch(88% 0.01 250);
   --accent: oklch(55% 0.18 150);
   --accent-bg: oklch(95% 0.04 150);
+  --accent-hover: oklch(50% 0.18 150);
   --warn: oklch(55% 0.16 30);
   --warn-bg: oklch(95% 0.04 30);
+  --input-bg: white;
+  --message-bg: oklch(96% 0.008 250);
+  --button-hover: oklch(96% 0.005 250);
+  --border-hover: oklch(80% 0.01 250);
+  --button-active: oklch(94% 0.008 250);
+  --pending-bg: oklch(96% 0.005 250);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --text: oklch(92% 0.01 250);
+    --text-muted: oklch(65% 0.015 250);
+    --surface: oklch(15% 0.02 250);
+    --border: oklch(32% 0.02 250);
+    --accent: oklch(70% 0.18 150);
+    --accent-bg: oklch(25% 0.06 150);
+    --accent-hover: oklch(65% 0.18 150);
+    --warn: oklch(70% 0.16 30);
+    --warn-bg: oklch(25% 0.06 30);
+    --input-bg: oklch(20% 0.02 250);
+    --message-bg: oklch(20% 0.02 250);
+    --button-hover: oklch(25% 0.02 250);
+    --border-hover: oklch(40% 0.02 250);
+    --button-active: oklch(28% 0.02 250);
+    --pending-bg: oklch(22% 0.02 250);
+  }
 }
 
 html {
@@ -46,7 +73,7 @@ h1 {
 /* Message from Ruby */
 .message-block {
   padding: 1rem 1.25rem;
-  background: oklch(96% 0.008 250);
+  background: var(--message-bg);
   border-left: 3px solid var(--border);
   margin-block-end: 2rem;
 }
@@ -82,7 +109,7 @@ input[type="text"] {
   font-family: inherit;
   font-size: 1rem;
   color: var(--text);
-  background: white;
+  background: var(--input-bg);
   border: 1px solid var(--border);
   border-radius: 6px;
   outline: none;
@@ -106,7 +133,7 @@ button {
   font-size: 0.875rem;
   font-weight: 500;
   color: var(--text);
-  background: white;
+  background: var(--input-bg);
   border: 1px solid var(--border);
   border-radius: 6px;
   cursor: pointer;
@@ -114,12 +141,12 @@ button {
 }
 
 button:hover {
-  background: oklch(96% 0.005 250);
-  border-color: oklch(80% 0.01 250);
+  background: var(--button-hover);
+  border-color: var(--border-hover);
 }
 
 button:active {
-  background: oklch(94% 0.008 250);
+  background: var(--button-active);
 }
 
 button[data-primary] {
@@ -129,8 +156,8 @@ button[data-primary] {
 }
 
 button[data-primary]:hover {
-  background: oklch(50% 0.18 150);
-  border-color: oklch(50% 0.18 150);
+  background: var(--accent-hover);
+  border-color: var(--accent-hover);
 }
 
 /* Status feedback */
@@ -158,7 +185,7 @@ button[data-primary]:hover {
 
 .feedback[data-type="pending"] {
   color: var(--text-muted);
-  background: oklch(96% 0.005 250);
+  background: var(--pending-bg);
 }
 
 /* IPC status indicator */

data/examples/verify_ping_pong/views/layout.erb

@@ -12,7 +12,7 @@ SPDX-License-Identifier: AGPL-3.0-or-later
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
   <link href="https://fonts.googleapis.com/css2?family=Instrument+Sans:wght@400;500;600&display=swap" rel="stylesheet">
-  <link rel="stylesheet" href="tokra://localhost/styles.css">
+  <link rel="stylesheet" href="/styles.css">
 </head>
 <body>
   <main>

data/examples/verify_rails_sqlite/.dockerignore

@@ -0,0 +1,51 @@
+# See https://docs.docker.com/engine/reference/builder/#dockerignore-file for more about ignoring files.
+
+# Ignore git directory.
+/.git/
+/.gitignore
+
+# Ignore bundler config.
+/.bundle
+
+# Ignore all environment files.
+/.env*
+
+# Ignore all default key files.
+/config/master.key
+/config/credentials/*.key
+
+# Ignore all logfiles and tempfiles.
+/log/*
+/tmp/*
+!/log/.keep
+!/tmp/.keep
+
+# Ignore pidfiles, but keep the directory.
+/tmp/pids/*
+!/tmp/pids/.keep
+
+# Ignore storage (uploaded files in development and any SQLite databases).
+/storage/*
+!/storage/.keep
+/tmp/storage/*
+!/tmp/storage/.keep
+
+# Ignore assets.
+/node_modules/
+/app/assets/builds/*
+!/app/assets/builds/.keep
+/public/assets
+
+# Ignore CI service files.
+/.github
+
+# Ignore Kamal files.
+/config/deploy*.yml
+/.kamal
+
+# Ignore development files
+/.devcontainer
+
+# Ignore Docker-related files
+/.dockerignore
+/Dockerfile*

data/examples/verify_rails_sqlite/.gitattributes

@@ -0,0 +1,9 @@
+# See https://git-scm.com/docs/gitattributes for more about git attribute files.
+
+# Mark the database schema as having been generated.
+db/schema.rb linguist-generated
+
+# Mark any vendored files as having been vendored.
+vendor/* linguist-vendored
+config/credentials/*.yml.enc diff=rails_credentials
+config/credentials.yml.enc diff=rails_credentials

data/examples/verify_rails_sqlite/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+- package-ecosystem: bundler
+  directory: "/"
+  schedule:
+    interval: weekly
+  open-pull-requests-limit: 10
+- package-ecosystem: github-actions
+  directory: "/"
+  schedule:
+    interval: weekly
+  open-pull-requests-limit: 10

data/examples/verify_rails_sqlite/.github/workflows/ci.yml

@@ -0,0 +1,124 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+
+jobs:
+  scan_ruby:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+
+      - name: Scan for common Rails security vulnerabilities using static analysis
+        run: bin/brakeman --no-pager
+      
+      - name: Scan for known security vulnerabilities in gems used
+        run: bin/bundler-audit
+      
+  scan_js:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+
+      - name: Scan for security vulnerabilities in JavaScript dependencies
+        run: bin/importmap audit
+
+  lint:
+    runs-on: ubuntu-latest
+    env:
+      RUBOCOP_CACHE_ROOT: tmp/rubocop
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+
+      - name: Prepare RuboCop cache
+        uses: actions/cache@v4
+        env:
+          DEPENDENCIES_HASH: ${{ hashFiles('.ruby-version', '**/.rubocop.yml', '**/.rubocop_todo.yml', 'Gemfile.lock') }}
+        with:
+          path: ${{ env.RUBOCOP_CACHE_ROOT }}
+          key: rubocop-${{ runner.os }}-${{ env.DEPENDENCIES_HASH }}-${{ github.ref_name == github.event.repository.default_branch && github.run_id || 'default' }}
+          restore-keys: |
+            rubocop-${{ runner.os }}-${{ env.DEPENDENCIES_HASH }}-
+
+      - name: Lint code for consistent style
+        run: bin/rubocop -f github
+
+  test:
+    runs-on: ubuntu-latest
+
+    # services:
+    #  redis:
+    #    image: valkey/valkey:8
+    #    ports:
+    #      - 6379:6379
+    #    options: --health-cmd "redis-cli ping" --health-interval 10s --health-timeout 5s --health-retries 5
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+
+      - name: Run tests
+        env:
+          RAILS_ENV: test
+          # RAILS_MASTER_KEY: ${{ secrets.RAILS_MASTER_KEY }}
+          # REDIS_URL: redis://localhost:6379/0
+        run: bin/rails db:test:prepare test
+
+  system-test:
+    runs-on: ubuntu-latest
+
+    # services:
+    #  redis:
+    #    image: valkey/valkey:8
+    #    ports:
+    #      - 6379:6379
+    #    options: --health-cmd "redis-cli ping" --health-interval 10s --health-timeout 5s --health-retries 5
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+
+      - name: Run System Tests
+        env:
+          RAILS_ENV: test
+          # RAILS_MASTER_KEY: ${{ secrets.RAILS_MASTER_KEY }}
+          # REDIS_URL: redis://localhost:6379/0
+        run: bin/rails db:test:prepare test:system
+
+      - name: Keep screenshots from failed system tests
+        uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: screenshots
+          path: ${{ github.workspace }}/tmp/screenshots
+          if-no-files-found: ignore

data/examples/verify_rails_sqlite/.gitignore

@@ -0,0 +1,35 @@
+# See https://help.github.com/articles/ignoring-files for more about ignoring files.
+#
+# Temporary files generated by your text editor or operating system
+# belong in git's global ignore instead:
+# `$XDG_CONFIG_HOME/git/ignore` or `~/.config/git/ignore`
+
+# Ignore bundler config.
+/.bundle
+
+# Ignore all environment files.
+/.env*
+
+# Ignore all logfiles and tempfiles.
+/log/*
+/tmp/*
+!/log/.keep
+!/tmp/.keep
+
+# Ignore pidfiles, but keep the directory.
+/tmp/pids/*
+!/tmp/pids/
+!/tmp/pids/.keep
+
+# Ignore storage (uploaded files in development and any SQLite databases).
+/storage/*
+!/storage/.keep
+/tmp/storage/*
+!/tmp/storage/
+!/tmp/storage/.keep
+
+/public/assets
+
+# Ignore key files for decrypting credentials and more.
+/config/*.key
+

data/examples/verify_rails_sqlite/.kamal/hooks/docker-setup.sample

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+echo "Docker set up on $KAMAL_HOSTS..."

data/examples/verify_rails_sqlite/.kamal/hooks/post-app-boot.sample

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+echo "Booted app version $KAMAL_VERSION on $KAMAL_HOSTS..."

data/examples/verify_rails_sqlite/.kamal/hooks/post-deploy.sample

@@ -0,0 +1,14 @@
+#!/bin/sh
+
+# A sample post-deploy hook
+#
+# These environment variables are available:
+# KAMAL_RECORDED_AT
+# KAMAL_PERFORMER
+# KAMAL_VERSION
+# KAMAL_HOSTS
+# KAMAL_ROLES (if set)
+# KAMAL_DESTINATION (if set)
+# KAMAL_RUNTIME
+
+echo "$KAMAL_PERFORMER deployed $KAMAL_VERSION to $KAMAL_DESTINATION in $KAMAL_RUNTIME seconds"