Skip to content
hrinkar01Public

About

Deterministic Time-Travel Debugger & Live Hot-Code Patcher

Resources

Stars

1 star

Watchers

1 watching

Forks

Latest commit

 

History

22 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Rewind

Time-Travel Debugger & In-Memory Hot-Code Patcher for Python

Record execution state history, scrub backward through function milestones, inspect variable mutations, and test fixes in memory before saving to disk.


Python 3.8+ Tests Dependencies License: MIT


Why Rewind?

When a script or pipeline crashes, Python produces a traceback:

TypeError: unsupported operand type(s) for +: 'float' and 'NoneType'
File "pipeline.py", line 38, in finalize_invoice
    final_total = order["subtotal"] + order["tax"]

The traceback shows where the code failed (the symptom), but not why order["tax"] was None (the root cause). The actual bug often happened several functions earlier (e.g., an unhandled condition in an upstream session initializer).

Traditional debuggers (pdb, IDE breakpoints) are forward-only and post-mortem:

  • Once the process crashes, execution terminates and in-memory state is lost.
  • Stepping too far means restarting the entire process from the beginning.
  • Finding where a variable was corrupted usually requires adding temporary print() calls and restarting repeatedly.

Rewind solves this by recording an execution timeline:

  1. Scrub Backward: Step backward through function frames (J / K) to see earlier states without restarting.
  2. Inspect Diffs: View exact variable additions, mutations, and deletions between function boundaries.
  3. Hot-Replay in RAM: Edit broken lines directly in the browser and re-execute in ~0.14 ms to verify fixes.
  4. Patch to Disk: Atomically write verified fixes to disk with automatic .bak backups.

How It Works

                        REWIND ARCHITECTURE

    ┌────────────────────────────────────────────────────────┐
    │ 1. Instrumentation (rewind/cli.py)                     │
    │    • Hooks Python execution via sys.settrace()         │
    │    • Captures inputs, outputs, and uncaught exceptions │
    └──────────────────────────┬─────────────────────────────┘
                               │
                               ▼
    ┌────────────────────────────────────────────────────────┐
    │ 2. State & Diff Engine (rewind/diff.py, tracer.py)     │
    │    • Circular-safe object serialization                │
    │    • Structural state diffing (+ Added, ~ Mutated)     │
    │    • Exports portable rewind_trace.json                │
    └──────────────────────────┬─────────────────────────────┘
                               │
                               ▼
    ┌────────────────────────────────────────────────────────┐
    │ 3. Web Scrubber & Hot Sandbox (localhost:8765)         │
    │    • Interactive timeline scrubber (J / K / Space)     │
    │    • Line-level crash focus & IDE gutter               │
    │    • POST /api/replay (In-memory execution in <1ms)    │
    │    • POST /api/patch  (Atomic disk writer with backup) │
    └────────────────────────────────────────────────────────┘

1. Semantic Milestone Tracing

Naive instruction-level tracing logs every bytecode or loop iteration, introducing 10x–30x runtime overhead. Rewind instead intercepts function boundaries (call, return, exception):

  • On call: Snapshots argument values at function entry and starts a high-resolution timer (time.perf_counter()).
  • On return: Records return values, computes state differences against the prior frame, and records step latency in microseconds.
  • On exception: Captures the traceback, exact file and line number, and marks the frame as FAILED.

2. Circular-Safe State Diffing

Complex objects frequently contain nested dictionaries, custom class instances, or circular references (a.child = b; b.parent = a). Rewind's serializer:

  • Tracks visited memory addresses via id(obj) in a set to avoid recursion limits.
  • Recursively computes structural diffs:
    • + Added: New keys introduced in the frame.
    • ~ Mutated: Modified values, displayed as previous_value → new_value.
    • - Removed: Deleted keys.

3. In-Memory Sandbox Replay

When testing code changes in the web dashboard, Rewind compiles and executes the modified script in RAM using compile() and exec(), with stdout and stderr redirected to memory buffers (io.StringIO). This provides sub-millisecond validation without creating child OS processes or modifying files on disk.


Comparison

Feature Standard Debugger (pdb, VS Code) Mozilla rr Rewind
Platform / Language Python, general Linux C/C++/Rust Python / Script Pipelines
Direction Forward-only Bidirectional Bidirectional (J / K)
State After Crash Lost on exit Replayable via GDB Frozen & visually inspectable
State Visibility Manual variable queries Memory watchpoints Automatic visual diffs (+, ~, -)
Fix Verification Re-run process from terminal Re-run from terminal In-memory hot replay in 0.14 ms
Trace Portability None Local machine only Portable JSON artifact
Dependencies Built-in Linux kernel counters Pure standard library (0 dependencies)

Installation

Clone and install in editable mode:

git clone https://github.com/hrinkar01/rewind.git
cd rewind
pip3 install -e .

Rewind has zero external dependencies and runs on Python 3.8+ using only standard library modules.


Usage

1. Trace a Python Script

Trace any script with zero code modifications:

rewind run tests/broken_pipeline.py
  • Intercepts execution and streams stdout/stderr to your terminal.
  • Captures fatal exceptions with source context and line attribution.
  • Automatically launches the web scrubber at http://localhost:8765.

2. Monitor Commands and Subprocesses

You can also run external commands, servers, or build scripts through Rewind:

# Node / Next.js
rewind exec npm run dev

# Go / Rust
rewind exec go run main.go
rewind exec cargo run

# Test suites
rewind exec pytest tests/

3. CI / Headless Mode

Run headlessly in CI/CD pipelines (GitHub Actions, GitLab CI):

rewind run --ci tests/broken_pipeline.py

Outputs a structured step summary and exits with code 0 on clean pass, or 1 if an exception occurred.

4. Manage the Web Dashboard Server

# Start viewer for an existing trace file
rewind view rewind_trace.json

# Check server status
rewind status

# Stop running Rewind web servers
rewind stop

Web Dashboard & Hot-Patcher

When an exception occurs, the web dashboard highlights the failure and positions the editor directly at the offending line:

💥 Crash at Line 38    finalize_invoice()    broken_pipeline.py:38    TypeError
ERROR: unsupported operand type(s) for +: 'float' and 'NoneType'
CAUSE: order['tax'] is None (cannot add float + None)

Keyboard Shortcuts

Key Action
J / ← Step backward to previous frame
K / → Step forward to next frame
Space Play / Pause continuous execution playback
Home / End Jump to first / last frame
⌘↵ / Ctrl+Enter Replay modified code in in-memory sandbox
⌘S / Ctrl+S Save validated fix to disk (creates .bak backup)

Programmatic SDK

You can also instrument specific application blocks using the context manager API:

from rewind import Tracer, step

tracer = Tracer(title="Order Processing Pipeline")

# Step 1: Initialize user session
with step("init_session", user_id="usr_102") as state:
    state["user"] = "Alice"
    state["cart"] = {"items": ["Keyboard"], "subtotal": 120.00}

# Step 2: Apply discount
with step("apply_discount", coupon="SAVE20") as state:
    state["cart"]["subtotal"] = 96.00
    state["cart"]["discount_applied"] = True

# Step 3: Export trace for web scrubbing
tracer.export("rewind_trace.json")

Test Suite

Run the unit tests:

python3 -m unittest discover -s tests -p "test_*.py" -v
Ran 16 tests in 0.045s

OK

Covers serialization safety (primitives, sets, classes, circular references), diff computation, multithreaded step recording, hot-replay execution, and CLI trace lifecycles.


License

Distributed under the MIT License. See LICENSE for details.

About

Deterministic Time-Travel Debugger & Live Hot-Code Patcher

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages