# ohm — Architecture

## Why ohm exists

Neovim's built-in LSP client starts a fresh server process per session. This creates several recurring problems in real-world use:

- **Memory bloat** — gopls for a large Go repo can use 500–1500MB. Three Neovim sessions = three copies.
- **Monorepo duplication** — opening the same root directory in multiple windows spawns redundant servers that index the same files independently.
- **Stuck diagnostics** — when a Neovim session closes, the LSP server receives no `textDocument/didClose`, leaving stale diagnostics on the next open.
- **Session degradation** — long-running LSP servers accumulate state; a server spawned fresh each session never benefits from warmup.

ohm moves the LSP server lifecycle out of Neovim and into a persistent daemon. One server per `{root_dir, language}` pair, shared across every Neovim session, for the lifetime of the workstation session.

---

## Two-socket design

ohm uses two distinct Unix sockets with different protocols:

```
┌─────────────────────────────────────────────────────┐
│  Neovim instance                                     │
│                                                      │
│  lspconfig (ohm --client per buffer)                 │
│       │ stdio  LSP JSON-RPC                          │
│       ▼                                              │
│  ohm --client bridge process                         │
│       │ unix socket  LSP JSON-RPC                   │
│       ▼                                              │
│  [proxy socket]  ◄──── per server, raw LSP           │
└─────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────┐
│  ohm daemon                                          │
│                                                      │
│  Mux (fan-out, ID rewriting)                         │
│       │ stdio  LSP JSON-RPC                          │
│       ▼                                              │
│  LSP server process (gopls, rust-analyzer, ...)      │
└─────────────────────────────────────────────────────┘

  [control socket]  ◄──── msgpack-rpc, persistent channel
         │
         ▼
  Neovim shim (client.lua rpcrequest/rpcnotify)
```

**Control socket** (`ohm.sock`) — speaks msgpack-rpc (Neovim's native RPC protocol). Used by the Lua plugin to send `attach`/`detach`/`status` commands. One persistent connection per Neovim instance.

**Proxy socket** (e.g. `ohm-go-a3f1b2c4.sock`) — speaks raw LSP JSON-RPC. One socket per registered `{root_dir, language}` server. The `ohm --client` bridge connects here and forwards bytes to/from Neovim's lspconfig.

Keeping the protocols separate avoids the corruption that plagued V1, where LSP frames and msgpack-rpc frames shared a single socket.

---

## Request flow

### Attach (new buffer opened)

1. Neovim opens `main.go` in a Go project.
2. lspconfig calls `vim.lsp.rpc.start`, which ohm's `wire_lspconfig` hook has overridden to launch `ohm --client --socket <sock> --root <dir> --lang go -- gopls`.
3. `ohm --client` connects to the control socket and sends a msgpack-rpc `attach` request.
4. The daemon looks up `{root_dir="...", lang="go"}` in the registry:
   - **Hit** — increments ref count, returns existing proxy socket path.
   - **Miss** — spawns a new `gopls` process, creates a `Mux`, binds a proxy socket, registers the server, returns the proxy socket path.
5. `ohm --client` disconnects from the control socket, connects to the proxy socket, and begins bridging `stdin ↔ proxy` bidirectionally.
6. Neovim's lspconfig now believes it is speaking directly to gopls.

### LSP request (e.g. hover)

```
Neovim  →  ohm --client (stdin→proxy)
        →  proxy socket  →  Mux.serveClient
        →  ID rewritten (client id → global id)
        →  WriteFrame to gopls stdin
        →  gopls processes request
        →  gopls stdout  →  Mux.Broadcast
        →  pending map lookup (global id → original client id + conn)
        →  ID restored
        →  WriteFrame to proxy socket
        →  ohm --client (proxy→stdout)  →  Neovim
```

### Server-pushed notification (e.g. publishDiagnostics)

```
gopls stdout  →  Mux.Broadcast
              →  no id, has method  →  broadcast path
              →  WriteFrame to every connected client
              →  all Neovim instances receive diagnostics
```

---

## Request ID rewriting

LSP uses numeric request IDs chosen by the client. With multiple Neovim sessions sharing one gopls, their IDs collide (every session starts at 1).

The Mux maintains a global atomic counter (`nextID`). On each incoming request:

1. The original client ID is saved in a `pending` map keyed by `globalID`.
2. The message body is rewritten with `globalID` before forwarding to gopls.
3. When gopls responds, `Broadcast` looks up `globalID` in the pending map, rewrites the ID back to the original client value, and routes the response to that client's connection only.

Notifications (no ID field) are broadcast to all clients since they are not responses to a specific request.

---

## initialize caching

The LSP `initialize` handshake is expensive: it triggers full project indexing in gopls. ohm ensures it happens exactly once per server lifetime.

```
First client                   Concurrent client           Later client
──────────────                 ─────────────────           ────────────
send initialize
  initInFlight = true ─────►  sees initInFlight=true
  forward to gopls             block on <-initReady
gopls responds
  cache initResponse
  close(initReady)  ──────►  unblocked
  send to client A             rewrite ID, send cached    send cached immediately
```

Three states tracked under `initMu`:
- `initResponse == nil`, `initInFlight == false` → first caller; forward to server
- `initResponse == nil`, `initInFlight == true` → concurrent caller; wait on `initReady` channel
- `initResponse != nil` → cached; return immediately with ID rewrite

The `initialized` notification (sent after `initialize` succeeds) is only forwarded for the first client. Subsequent clients skip it via the same caching path.

---

## Shutdown interception

When a Neovim session closes, lspconfig sends `shutdown` then `exit`. Forwarding these to gopls would kill the shared server.

`serveClient` intercepts both:

- **`shutdown`** — a fake `{"result": null}` response is sent back to the client immediately. The request is never forwarded.
- **`exit`** (notification, no ID) — silently dropped.

gopls never sees either message and stays running.

---

## Ref counting and grace period

Each `LSPServer` tracks a `Refs` count — the number of `ohm --client` bridge processes currently connected to its proxy socket.

- `attach` → `IncrRef`
- `detach` → `DecrRef`

When `Refs` reaches 0, a 10-second timer starts (`pendingKill`). If a new `attach` arrives within the window the timer is cancelled and the server is reused immediately. After 10 seconds the server is shut down gracefully.

This handles the common case of closing and immediately reopening a file, or switching between splits.

---

## Respawn

When a server process exits unexpectedly (gopls crash, OOM kill), `Mux.Broadcast` reads EOF from the process stdout and calls `mux.onExit`, which triggers `respawnServer`.

`respawnServer`:
1. Cancels any in-flight `pendingKill` timer for the key (a crash during the grace period must not let the timer kill the new process).
2. Spawns a fresh LSP process.
3. Creates a new `Mux` for the new process.
4. Swaps `server.Process` and `server.mux` in place under `server.mu`.
5. Starts `Broadcast` on the new mux.

The proxy socket listener (`listenProxy`) keeps running throughout — it holds no reference to the old mux. New connections arriving after the swap go to the new mux automatically.

Existing Neovim clients connected to the old mux will see their `serveClient` goroutines exit (write errors to a dead process), disconnect, and reconnect on the next LSP request via lspconfig.

---

## Watchdog

A goroutine wakes every 30 seconds and checks every registered server:

| Check | Threshold | Action |
|---|---|---|
| RSS memory | > 1500 MB | graceful shutdown + remove |
| Last response age | > 5 minutes | graceful shutdown + remove |

Memory is read from `/proc/{pid}/status` (VmRSS). Last response time is an atomic timestamp updated on every message received from the server's stdout.

Both checks call `server.Close()` which sends a graceful LSP `shutdown`+`exit` sequence before killing the process. `mux.onExit` then triggers a respawn.

---

## Graceful shutdown sequence

`Mux.GracefulShutdown`:

1. Register a synthetic internal `pending` entry (no client, just a `done` channel).
2. Send `{"method":"shutdown","id":<globalID>}` to the server.
3. Wait up to 5 seconds for the response on `done`.
4. Send `{"method":"exit"}` notification.
5. Wait up to 2 seconds for the process to exit.
6. If still running after step 5, `Kill()`.

---

## Concurrency model

| Goroutine | Lifetime | What it does |
|---|---|---|
| `handleConn` | per control connection | decodes msgpack-rpc, dispatches attach/detach/status |
| `Broadcast` | per LSP server | reads server stdout, routes to clients |
| `serveClient` | per proxy client | reads client frames, rewrites IDs, writes to server stdin |
| `sendLoop` | per proxy client | drains send channel, writes frames to client conn |
| `listenProxy` | per LSP server | accepts new proxy connections |
| `captureStderr` | per LSP server | pipes server stderr to slog |
| `watchdog` | singleton | periodic memory + frozen checks |
| `respawnServer` | on crash | runs as `go m.onExit()` from Broadcast |

Shared state and its lock:

| State | Lock |
|---|---|
| `registry.servers` | `registry.mu` |
| `daemon.pendingKill` | `daemon.mu` |
| `mux.clients` | `mux.clientsMu` (RWMutex) |
| `mux.pending` | `mux.pendingMu` |
| `mux.initResponse / initInFlight` | `mux.initMu` |
| `server.mux / server.Process` | `server.mu` (RWMutex) |
| `mux.lastNs` | atomic |
| `mux.nextID` | atomic |