fix: docs directory cleaning
This commit is contained in:
Developer
parent
7f05b03a76
commit
b432ea557d
7 changed files with 0 additions and 189 deletions
|
|
@ -1,74 +0,0 @@
|
||||||
# Dead-Node Reprobe — Design & Rationale
|
|
||||||
|
|
||||||
## Problem
|
|
||||||
|
|
||||||
When a network partition heals, SWIM nodes on both sides may have declared each
|
|
||||||
other Dead. The `alive_members()` filter excludes Dead nodes from probing
|
|
||||||
targets, so neither side initiates communication — creating a **permanent split**
|
|
||||||
even after connectivity is restored.
|
|
||||||
|
|
||||||
The existing refutation mechanism (incarnation bump on learning of own death
|
|
||||||
declaration) handles resurrection correctly, but depends on someone *telling*
|
|
||||||
the dead-declared node about its status. With no probes to dead nodes, nobody
|
|
||||||
does.
|
|
||||||
|
|
||||||
## Solution: Independent Dead-Node Reprobe Cycle
|
|
||||||
|
|
||||||
Added a lightweight reprobe mechanism to `SwimProbe` that periodically pings
|
|
||||||
dead nodes. The existing piggyback + refutation mechanism handles the rest:
|
|
||||||
|
|
||||||
1. **Reprober** pings dead node with piggybacked "you are Dead(inc=N)"
|
|
||||||
2. **Target** receives piggyback, sees it's declared Dead → refutes → bumps incarnation
|
|
||||||
3. **Target** replies with Ack carrying piggybacked "I'm Alive(new_inc)"
|
|
||||||
4. **Reprober** applies piggyback → target transitions Dead→Alive
|
|
||||||
|
|
||||||
Key insight: we re-enqueue the death declaration in the dissemination queue
|
|
||||||
before packing the reprobe ping's piggyback. Without this, the original death
|
|
||||||
declaration's transmit budget would be long exhausted, and the piggyback would
|
|
||||||
carry no useful membership info.
|
|
||||||
|
|
||||||
## Design Decisions
|
|
||||||
|
|
||||||
### Why inside SwimProbe (not SwimNode)?
|
|
||||||
|
|
||||||
- SwimProbe owns the tick counter, sequence counter, and member list access
|
|
||||||
- All probe-related logic stays in one place
|
|
||||||
- The reprobe is a simple independent cycle — doesn't interfere with ProbePhase
|
|
||||||
|
|
||||||
### Why no new wire messages?
|
|
||||||
|
|
||||||
- `SwimAction::SendPing` works identically for normal probes and reprobes
|
|
||||||
- The ack from a reprobe targets a different sequence than the current probe
|
|
||||||
cycle, so the probe state machine ignores it — but the piggyback is applied
|
|
||||||
at the SwimNode layer before the probe state machine sees the ack
|
|
||||||
|
|
||||||
### Configuration
|
|
||||||
|
|
||||||
- `dead_reprobe_interval: u64` (default: 50 ticks, ~5× probe_interval)
|
|
||||||
- Set to 0 to disable completely
|
|
||||||
- Existing test configs use 0 to avoid interference with timing
|
|
||||||
|
|
||||||
## Files Changed
|
|
||||||
|
|
||||||
| File | Change |
|
|
||||||
|------|--------|
|
|
||||||
| `crates/distribution/src/swim/probe.rs` | `dead_reprobe_interval` in config, `maybe_reprobe_dead()` method |
|
|
||||||
| `crates/distribution/src/swim/member_list.rs` | Added `dead_members()` |
|
|
||||||
| `crates/distribution/src/swim/node.rs` | Re-enqueue death declaration in `translate_probe_actions` |
|
|
||||||
| All `SwimConfig` struct literals | Added `dead_reprobe_interval` field |
|
|
||||||
|
|
||||||
## Edge Cases
|
|
||||||
|
|
||||||
- **Truly dead nodes**: Reprobe ping is lost (no ack), no harm done
|
|
||||||
- **All members dead**: Reprobe cycles through them round-robin
|
|
||||||
- **Concurrent reprobe + normal probe**: Independent, different sequences
|
|
||||||
- **Dissemination budget**: Death re-enqueued fresh each reprobe, not stale
|
|
||||||
|
|
||||||
## Alternatives Considered
|
|
||||||
|
|
||||||
1. **Dead node grace period + resurrection timer**: More complex, adds new
|
|
||||||
state tracking alongside suspicion timers. Rejected for simplicity.
|
|
||||||
2. **Periodic re-join via seed nodes**: Requires seed node availability,
|
|
||||||
doesn't work when seed is itself dead-declared. Rejected.
|
|
||||||
3. **Direct liveness inference from Ping reception**: Would require changing
|
|
||||||
`handle_ping` to special-case pings from dead nodes. More invasive.
|
|
||||||
|
|
@ -1,115 +0,0 @@
|
||||||
# Wasm Actor
|
|
||||||
|
|
||||||
The `swactor-wasm-actor` crate runs WebAssembly guest code inside a swactor
|
|
||||||
actor. The Wasm instance is sandboxed by [wasmtime](https://wasmtime.dev/).
|
|
||||||
|
|
||||||
## Architecture
|
|
||||||
|
|
||||||
```
|
|
||||||
┌─ Runtime ──────────────────────────────────────────────────────────────┐
|
|
||||||
│ │
|
|
||||||
│ ┌─ WasmActor ──────────────────────────────────────────────────────┐ │
|
|
||||||
│ │ │ │
|
|
||||||
│ │ Store<HostState> -- wasmtime store with outbox │ │
|
|
||||||
│ │ Memory -- guest linear memory │ │
|
|
||||||
│ │ alloc: TypedFunc -- guest allocator │ │
|
|
||||||
│ │ handle: TypedFunc -- guest message handler │ │
|
|
||||||
│ │ │ │
|
|
||||||
│ │ impl ActorInterface for WasmActor │ │
|
|
||||||
│ │ Incoming = ByteMessage │ │
|
|
||||||
│ │ Response = () │ │
|
|
||||||
│ │ │ │
|
|
||||||
│ └──────────────────────────────────────────────────────────────────┘ │
|
|
||||||
│ │
|
|
||||||
│ ┌─ Native Actors ─────────────────────────────────────────────────┐ │
|
|
||||||
│ │ (can exchange ByteMessage with WasmActors normally) │ │
|
|
||||||
│ └─────────────────────────────────────────────────────────────────┘ │
|
|
||||||
│ │
|
|
||||||
└────────────────────────────────────────────────────────────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
## Message Flow
|
|
||||||
|
|
||||||
```
|
|
||||||
Host Guest (Wasm)
|
|
||||||
──── ────────────
|
|
||||||
|
|
||||||
ByteMessage arrives
|
|
||||||
│
|
|
||||||
├─1─ call alloc(len) ──────────► bump-allocate, return ptr
|
|
||||||
│
|
|
||||||
├─2─ write bytes at ptr ───────► (memory updated)
|
|
||||||
│
|
|
||||||
├─3─ call handle(ptr, len) ────► process message
|
|
||||||
│ │
|
|
||||||
│ ◄── swactor.send() ────────────┤ (0..N times)
|
|
||||||
│ (buffered in HostState.outbox) │
|
|
||||||
│ │
|
|
||||||
├─4─ drain outbox ◄────────────── handle returns
|
|
||||||
│
|
|
||||||
v
|
|
||||||
ctx.send(dest, ByteMessage) for each outbox entry
|
|
||||||
```
|
|
||||||
|
|
||||||
## Guest Contract
|
|
||||||
|
|
||||||
Guests are standalone `wasm32-unknown-unknown` modules. They export three
|
|
||||||
symbols and may import one:
|
|
||||||
|
|
||||||
| Direction | Module | Symbol | Signature |
|
|
||||||
|-----------|--------|--------|-----------|
|
|
||||||
| **export** | — | `memory` | linear memory |
|
|
||||||
| **export** | — | `alloc` | `(i32) -> i32` |
|
|
||||||
| **export** | — | `handle` | `(i32, i32) -> ()` |
|
|
||||||
| **import** | `swactor` | `send` | `(i32, i32, i32) -> ()` |
|
|
||||||
|
|
||||||
The `send` import takes `(dest_ptr, payload_ptr, payload_len)` where
|
|
||||||
`dest_ptr` points to a 32-byte `ActorAddress` in guest memory.
|
|
||||||
|
|
||||||
## Usage
|
|
||||||
|
|
||||||
```rust
|
|
||||||
use swactor::runtime::{Runtime, RuntimeConfig};
|
|
||||||
use swactor_wasm_actor::{ByteMessage, SharedEngine, WasmActorBuilder};
|
|
||||||
|
|
||||||
// Create a shared engine (once)
|
|
||||||
let engine = SharedEngine::new().unwrap();
|
|
||||||
|
|
||||||
// Build an actor from .wasm bytes
|
|
||||||
let wasm_bytes = std::fs::read("my_guest.wasm").unwrap();
|
|
||||||
let actor = WasmActorBuilder::new(engine, wasm_bytes)
|
|
||||||
.build()
|
|
||||||
.unwrap();
|
|
||||||
|
|
||||||
// Use it like any other actor
|
|
||||||
let rt = Runtime::new(RuntimeConfig::default());
|
|
||||||
let addr = rt.spawn(actor).unwrap();
|
|
||||||
rt.send_to(addr, ByteMessage(b"hello".to_vec())).unwrap();
|
|
||||||
rt.tick();
|
|
||||||
```
|
|
||||||
|
|
||||||
## Sandboxing
|
|
||||||
|
|
||||||
The `SharedEngine` disables all optional Wasm proposals:
|
|
||||||
|
|
||||||
- Threads — disabled
|
|
||||||
- SIMD / relaxed SIMD — disabled
|
|
||||||
- Reference types — disabled
|
|
||||||
- Multi-value — disabled
|
|
||||||
- Bulk memory — **enabled** (required by most Rust/LLVM toolchains)
|
|
||||||
|
|
||||||
No WASI imports are linked. Guests have no access to the filesystem, network,
|
|
||||||
clock, or random number generator. The only host function available is
|
|
||||||
`swactor.send`.
|
|
||||||
|
|
||||||
## Where Things Live
|
|
||||||
|
|
||||||
| File | Purpose |
|
|
||||||
|------|---------|
|
|
||||||
| `crates/wasm-actor/src/lib.rs` | `ByteMessage` + re-exports |
|
|
||||||
| `crates/wasm-actor/src/engine.rs` | `SharedEngine` — sandboxed wasmtime config |
|
|
||||||
| `crates/wasm-actor/src/builder.rs` | `WasmActorBuilder` — compile, link, instantiate |
|
|
||||||
| `crates/wasm-actor/src/actor.rs` | `WasmActor` — `ActorInterface` impl |
|
|
||||||
| `crates/wasm-actor/src/error.rs` | `WasmActorError` |
|
|
||||||
| `crates/wasm-actor/tests/guests/` | Three test guest crates (echo, double, silent) |
|
|
||||||
| `crates/wasm-actor/tests/wasm_actor.rs` | 7 integration tests |
|
|
||||||
Loading…
Reference in a new issue