[CHORE] Prepare v1.0.0 release with enhanced documentation

vereis · vereis · commit db238df6984d · 2025-12-27T18:43:38.000Z
diff --git a/README.md b/README.md
@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="https://github.com/user-attachments/assets/fde2b47f-d853-4ee3-bdad-54a18b852730" alt="EctoLiteFS" style="max-width: 100%; height: auto;" />
+</p>
+
 # EctoLiteFS
 
 LiteFS-aware Ecto middleware for automatic write forwarding in distributed SQLite clusters.
@@ -6,44 +10,108 @@ EctoLiteFS detects which node is the current LiteFS primary and automatically fo
 write operations to it, allowing replicas to handle reads locally while writes are
 transparently routed to the primary.
 
+> **Built on [EctoMiddleware](https://hex.pm/packages/ecto_middleware):** EctoLiteFS includes
+> EctoMiddleware as a dependency, so installing `ecto_litefs` gives you everything you need!
+
+## Features
+
+- **Automatic write forwarding** - Writes on replicas are transparently forwarded to primary
+- **Local reads** - Replicas handle reads locally for low latency
+- **Multiple detection methods** - Filesystem polling + HTTP event stream + database tracking
+- **Zero-config in dev/test** - Gracefully degrades when LiteFS is not present
+- **Minimal setup** - Just add middleware and a supervisor to your app
+- **Works with multiple repos** - Can track any number of Ecto repos in the same app
+- **Telemetry integration** - Monitor write forwarding performance and failures
+
 ## Installation
 
 Add `ecto_litefs` to your list of dependencies in `mix.exs`:
 
 ```elixir
 def deps do
   [
-    {:ecto_litefs, "~> 0.1.0"}
+    {:ecto_litefs, "~> 1.0"}
   ]
 end
 ```
 
-## Usage
+## Quick Start
+
+### 1. Add to Supervision Tree
+
+Add `EctoLiteFS.Supervisor` to your application, **after** your Repo:
+
+```elixir
+defmodule MyApp.Application do
+  def start(_type, _args) do
+    children = [
+      MyApp.Repo,
+      {EctoLiteFS.Supervisor,
+        repo: MyApp.Repo,
+        primary_file: "/litefs/.primary",
+        poll_interval: 30_000,
+        event_stream_url: "http://localhost:20202/events"
+      }
+    ]
+
+    Supervisor.start_link(children, strategy: :one_for_one)
+  end
+end
+```
+
+### 2. Add Middleware to Repo
 
-Add the supervisor to your application's supervision tree, after your Repo:
+```elixir
+defmodule MyApp.Repo do
+  use Ecto.Repo, otp_app: :my_app
+  use EctoMiddleware.Repo  # Included with ecto_litefs!
+
+  @impl EctoMiddleware.Repo
+  def middleware(_action, _resource) do
+    [EctoLiteFS.Middleware] # Add anywhere in your middleware stack
+  end
+end
+```
+
+### 3. Use Your Repo Normally
 
 ```elixir
-children = [
-  MyApp.Repo,
-  {EctoLiteFS.Supervisor,
-    repo: MyApp.Repo,
-    primary_file: "/litefs/.primary",
-    poll_interval: 30_000,
-    event_stream_url: "http://localhost:20202/events"
-  }
-]
+# On primary node - executes locally
+MyApp.Repo.insert!(%User{name: "Alice"})
+
+# On replica node - automatically forwarded to primary
+MyApp.Repo.insert!(%User{name: "Bob"})
+
+# Reads always execute locally (low latency!)
+MyApp.Repo.all(User)
 ```
 
+That's it! Writes are automatically forwarded when running on a replica.
+
+> **Future Plans:** Support for forwarding transactions and bulk operations is planned for future releases.
+
 ## Configuration Options
 
-* `:repo` - Required. The Ecto Repo module to track.
+All options are configured when starting the supervisor:
+
+* `:repo` - **Required**. The Ecto Repo module to track.
 * `:primary_file` - Path to LiteFS `.primary` file. Default: `"/litefs/.primary"`
 * `:poll_interval` - Filesystem poll interval in ms. Default: `30_000`
 * `:event_stream_url` - LiteFS HTTP events endpoint. Default: `"http://localhost:20202/events"`
 * `:table_name` - Database table for primary tracking. Default: `"_ecto_litefs_primary"`
 * `:cache_ttl` - Cache TTL in ms. Default: `5_000`
 * `:erpc_timeout` - Timeout for RPC calls to primary. Default: `15_000`
 
+### Minimal Configuration
+
+For most use cases, you only need to specify `:repo`:
+
+```elixir
+{EctoLiteFS.Supervisor, repo: MyApp.Repo}
+```
+
+All other options use sensible defaults that work with standard LiteFS configurations.
+
 ## How It Works
 
 EctoLiteFS uses multiple detection methods to determine primary status:
@@ -55,6 +123,72 @@ EctoLiteFS uses multiple detection methods to determine primary status:
 When a write operation is detected on a replica node, it's automatically forwarded
 to the primary node via `:erpc.call/4`.
 
+By default, both filesystem polling and event streaming are enabled for robust detection, but either
+of these can be disabled if desired.
+
+### Architecture
+
+```
+┌─────────────────────┐         ┌─────────────────────┐
+│   Primary Node      │         │   Replica Node      │
+│                     │         │                     │
+│  ┌──────────────┐   │         │  ┌──────────────┐   │
+│  │ Repo.insert  │   │  :erpc  │  │ Repo.insert  │───┼──┐
+│  └──────┬───────┘   │ ◄───────┼──│   (forwarded)│   │  │
+│         │           │         │  └──────────────┘   │  │
+│    ┌────▼────┐      │         │                     │  │
+│    │ SQLite  │◄─────┼─────────┼─► Reads happen      │  │
+│    │ (write) │      │ replicate│   locally          │  │
+│    └─────────┘      │         │                     │  │
+└─────────────────────┘         └─────────────────────┘  │
+                                                         │
+                    Middleware detects write ────────────┘
+                    and forwards to primary
+```
+
+## Development & Testing
+
+EctoLiteFS gracefully handles environments where LiteFS is not present:
+
+- **Production (with LiteFS):** Forwards writes to primary, reads from replica
+- **Development/Test (no LiteFS):** Executes all operations locally
+
+This means you can add the middleware to your Repo without any conditional logic -
+it will "just work" in all environments!
+
+## Monitoring with Telemetry
+
+EctoLiteFS emits telemetry events for observability:
+
+```elixir
+# Monitor slow write forwards
+:telemetry.attach(
+  "log-slow-forwards",
+  [:ecto_litefs, :forward, :stop],
+  fn _event, %{duration: duration}, %{repo: repo, action: action}, _config ->
+    if duration > 5_000_000 do  # 5ms
+      Logger.warning("Slow forward: #{action} took #{duration}ns")
+    end
+  end,
+  nil
+)
+
+# Track forwarding failures
+:telemetry.attach(
+  "track-forward-errors",
+  [:ecto_litefs, :forward, :exception],
+  fn _event, _measurements, %{repo: repo, reason: reason}, _config ->
+    Logger.error("Forward failed: #{inspect(reason)}")
+  end,
+  nil
+)
+```
+
+Available events:
+- `[:ecto_litefs, :forward, :start]` - Write forwarding initiated
+- `[:ecto_litefs, :forward, :stop]` - Forwarding completed successfully
+- `[:ecto_litefs, :forward, :exception]` - Forwarding failed
+
 ## Testing
 
 ### Unit Tests
@@ -84,6 +218,14 @@ Test scenarios:
 3. Write forwarding from replica to primary
 4. Primary failover - replica promoted, data preserved
 
+## Similar Projects
+
+- **[litefs](https://hex.pm/packages/litefs)** - The original LiteFS library for Elixir by [@sheertj](https://git.sr.ht/~sheertj). 
+  Uses a repo wrapper approach where you rename your repo to `MyApp.Repo.Local` and create a new 
+  `MyApp.Repo` that proxies writes, and relies on filesystem polling only. EctoLiteFS differs by 
+  using middleware instead (so your existing repo stays unchanged), and adds HTTP event streaming 
+  for faster primary detection.
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) for details.
diff --git a/lib/ecto_litefs.ex b/lib/ecto_litefs.ex
@@ -6,9 +6,47 @@ defmodule EctoLiteFS do
   write operations to it, allowing replicas to handle reads locally while writes are
   transparently routed to the primary.
 
-  ## Usage
+  > **Built on EctoMiddleware:** EctoLiteFS is powered by [EctoMiddleware](https://hex.pm/packages/ecto_middleware),
+  > which is included as a dependency. Installing `ecto_litefs` gives you everything you need!
 
-  Add the supervisor to your application's supervision tree, after your Repo:
+  ## Quick Example
+
+      # 1. Add EctoLiteFS supervisor to your application
+      defmodule MyApp.Application do
+        def start(_type, _args) do
+          children = [
+            MyApp.Repo,
+            {EctoLiteFS.Supervisor, repo: MyApp.Repo}
+          ]
+
+          Supervisor.start_link(children, strategy: :one_for_one)
+        end
+      end
+
+      # 2. Add middleware to your Repo
+      defmodule MyApp.Repo do
+        use Ecto.Repo, otp_app: :my_app
+        use EctoMiddleware.Repo
+
+        @impl EctoMiddleware.Repo
+        def middleware(_action, _resource) do
+          [EctoLiteFS.Middleware]
+        end
+      end
+
+      # 3. Use your Repo normally - writes are automatically forwarded!
+      # On primary node:
+      MyApp.Repo.insert!(%User{name: "Alice"})  # Executes locally
+
+      # On replica node:
+      MyApp.Repo.insert!(%User{name: "Bob"})    # Forwarded to primary via :erpc
+      MyApp.Repo.all(User)                      # Reads locally from replica
+
+  ## Setup
+
+  ### 1. Add to Supervision Tree
+
+  Add `EctoLiteFS.Supervisor` to your application's supervision tree, **after** your Repo:
 
       children = [
         MyApp.Repo,
@@ -20,6 +58,22 @@ defmodule EctoLiteFS do
         }
       ]
 
+  ### 2. Add Middleware to Repo
+
+  EctoLiteFS uses [EctoMiddleware](https://hex.pm/packages/ecto_middleware) (included as a dependency):
+
+      defmodule MyApp.Repo do
+        use Ecto.Repo, otp_app: :my_app
+        use EctoMiddleware.Repo  # Comes with ecto_litefs!
+
+        @impl EctoMiddleware.Repo
+        def middleware(_action, _resource) do
+          [EctoLiteFS.Middleware]  # Add alongside other middleware if needed
+        end
+      end
+
+  That's it! Writes will automatically be forwarded to the primary node when running on a replica.
+
   ## Configuration Options
 
   * `:repo` - Required. The Ecto Repo module to track (also serves as the unique identifier).
@@ -29,6 +83,96 @@ defmodule EctoLiteFS do
   * `:table_name` - Database table for primary tracking. Default: `"_ecto_litefs_primary"`
   * `:cache_ttl` - Cache TTL in ms. Default: `5_000`
   * `:erpc_timeout` - Timeout for `:erpc` calls when forwarding writes to primary. Default: `15_000`
+
+  ## How It Works
+
+  EctoLiteFS uses multiple detection methods to determine primary status:
+
+  1. **Filesystem polling** - Checks for the presence of LiteFS's `.primary` file
+  2. **Event streaming** - Subscribes to LiteFS's HTTP event stream for real-time updates
+  3. **Database tracking** - Stores primary node information in a replicated table
+
+  When a write operation is detected on a replica node, it's automatically forwarded
+  to the primary node via `:erpc.call/4`.
+
+  ### Primary Detection
+
+  The Tracker process maintains an ETS cache of the current primary node, refreshed from
+  the database when stale. This ensures low-latency reads while maintaining consistency.
+
+  ### Write Forwarding
+
+  The middleware intercepts write operations (insert, update, delete) and checks if the
+  current node is the primary. If not, it forwards the operation to the primary using
+  `:erpc.call/4` with a configurable timeout.
+
+  ## Development & Test Mode
+
+  When `EctoLiteFS.Supervisor` is not started (e.g., in dev/test), the middleware
+  automatically passes through to local execution. This means you can add the
+  middleware to your Repo and it will "just work" in all environments:
+
+  - **Production (with LiteFS):** Forwards writes to primary node
+  - **Development/Test (no LiteFS):** Executes writes locally
+
+  ## Telemetry Events
+
+  EctoLiteFS emits telemetry events for observability:
+
+  - `[:ecto_litefs, :forward, :start]` - Write forwarding initiated
+  - `[:ecto_litefs, :forward, :stop]` - Forwarding completed successfully
+  - `[:ecto_litefs, :forward, :exception]` - Forwarding failed
+
+  All events include metadata: `%{repo: repo, action: action, primary_node: node}`
+
+  ### Example: Monitoring Write Forwarding
+
+      :telemetry.attach(
+        "log-write-forwards",
+        [:ecto_litefs, :forward, :stop],
+        fn _event, %{duration: duration}, %{repo: repo, action: action}, _config ->
+          Logger.info("Forwarded \#{action} to primary in \#{duration}ns")
+        end,
+        nil
+      )
+
+  ## Error Handling
+
+  - `{:error, :primary_unavailable}` - No primary node is known (cluster may be initializing)
+  - `{:error, {:erpc, :timeout, node}}` - RPC call timed out
+  - `{:error, {:erpc, :noconnection, node}}` - Primary node is unreachable
+
+  > #### Timeout Warning {: .warning}
+  >
+  > A timeout error does **not** mean the write failed. The primary node may have
+  > completed the write before the timeout occurred. Design your application to
+  > handle this uncertainty (e.g., idempotent writes, conflict resolution).
+
+  ## Limitations
+
+  - **Transactions:** Write forwarding within `Repo.transaction/2` is not currently
+    supported. Transactions must execute entirely on the primary node.
+
+  ## Public API
+
+  While the middleware handles most operations automatically, you can also use the
+  public API for direct control:
+
+      # Check if current node is primary
+      EctoLiteFS.is_primary?(MyApp.Repo)
+      #=> true
+
+      # Get current primary node
+      EctoLiteFS.get_primary(MyApp.Repo)
+      #=> {:ok, :node1@host}
+
+      # Manually set primary (usually not needed)
+      EctoLiteFS.set_primary(MyApp.Repo, node())
+      #=> :ok
+
+      # Invalidate cache (force refresh from DB)
+      EctoLiteFS.invalidate_cache(MyApp.Repo)
+      #=> :ok
   """
 
   alias EctoLiteFS.Tracker
diff --git a/lib/ecto_litefs/rpc.ex b/lib/ecto_litefs/rpc.ex
@@ -18,6 +18,7 @@ defmodule EctoLiteFS.RPC do
     - The result of the function execution
     - Raises :erpc exceptions on timeout, noconnection, etc.
   """
+  @spec call(node(), (-> term()), pos_integer()) :: term()
   def call(node, fun, timeout) do
     :erpc.call(node, fun, timeout)
   end
diff --git a/mix.exs b/mix.exs
