# Shared State

The pad is feature-complete. In this final chapter we take it one step
further: make it **collaborative**. Multiple people connect to the same
pad over SSH and see each other's changes in real time.

## Architecture

Plushie apps communicate with the renderer over a byte stream. By
default that stream is stdio to a local process, but it can be any
transport, including an SSH channel. We will build a server that
accepts SSH connections and gives each client a live view of the
shared pad state.

```
 ssh client 1 ──SSH──┐
                      ├── Shared GenServer ── PlushiePad.update/2
 ssh client 2 ──SSH──┘        │
                          broadcasts
                          model to all
```

Each client gets an SSH channel adapter that speaks the Plushie wire
protocol. Events from any client go through `update/2`, and the new
model is broadcast to everyone.

## Shared state server

The shared GenServer holds the authoritative model and a registry of
connected clients:

```elixir
defmodule PlushiePad.Shared do
  use GenServer

  def start_link(opts \\ []), do: GenServer.start_link(__MODULE__, :ok, opts)

  def connect(server, client_id),
    do: GenServer.call(server, {:connect, client_id, self()})

  def disconnect(server, client_id),
    do: GenServer.cast(server, {:disconnect, client_id})

  def event(server, event),
    do: GenServer.cast(server, {:event, event})

  @impl true
  def init(:ok) do
    {:ok, %{model: PlushiePad.init([]), clients: %{}}}
  end

  @impl true
  def handle_call({:connect, id, pid}, _from, state) do
    Process.monitor(pid)
    clients = Map.put(state.clients, id, pid)
    broadcast(clients, state.model)
    {:reply, :ok, %{state | clients: clients}}
  end

  @impl true
  def handle_cast({:disconnect, id}, state) do
    {:noreply, %{state | clients: Map.delete(state.clients, id)}}
  end

  @impl true
  def handle_cast({:event, event}, state) do
    model = PlushiePad.update(state.model, event)
    broadcast(state.clients, model)
    {:noreply, %{state | model: model}}
  end

  @impl true
  def handle_info({:DOWN, _ref, :process, pid, _reason}, state) do
    clients =
      state.clients
      |> Enum.reject(fn {_id, p} -> p == pid end)
      |> Map.new()

    {:noreply, %{state | clients: clients}}
  end

  defp broadcast(clients, model) do
    Enum.each(clients, fn {_id, pid} ->
      send(pid, {:model_changed, model})
    end)
  end
end
```

When any client sends an event, the server runs `PlushiePad.update/2`
and broadcasts the new model to all connected clients. Process
monitoring cleans up crashed connections automatically.

## SSH channel adapter

Each SSH connection gets a channel adapter that speaks the Plushie wire
protocol (MessagePack with 4-byte length-prefixed framing):

```elixir
defmodule PlushiePad.SshChannel do
  @behaviour :ssh_server_channel

  alias Plushie.Event.WidgetEvent
  alias Plushie.Transport.Framing

  defstruct [:shared, :client_id, :conn, :channel, buffer: <<>>, handshake_done: false]

  @impl true
  def init([shared]) do
    {:ok, %__MODULE__{shared: shared, client_id: "ssh-#{:erlang.unique_integer([:positive])}"}}
  end

  @impl true
  def handle_msg({:ssh_channel_up, channel, conn}, state) do
    state = %{state | conn: conn, channel: channel}

    settings =
      Plushie.Protocol.encode_settings(
        %{"antialiasing" => true, "default_text_size" => 16.0},
        :msgpack
      )

    send_packet(state, settings)
    {:ok, state}
  end

  def handle_msg({:model_changed, model}, state) do
    if state.handshake_done, do: send_snapshot(model, state)
    {:ok, state}
  end

  def handle_msg(_msg, state), do: {:ok, state}

  @impl true
  def handle_ssh_msg({:ssh_cm, _conn, {:data, _channel, 0, data}}, state) do
    combined = state.buffer <> data
    {frames, buffer} = Framing.decode_packets(combined)
    state = Enum.reduce(frames, state, &handle_frame/2)
    {:ok, %{state | buffer: buffer}}
  end

  def handle_ssh_msg({:ssh_cm, _conn, {:closed, _channel}}, state) do
    {:stop, state.channel, state}
  end

  def handle_ssh_msg(_msg, state), do: {:ok, state}

  @impl true
  def terminate(_reason, state) do
    if state.handshake_done,
      do: PlushiePad.Shared.disconnect(state.shared, state.client_id)

    :ok
  end

  defp handle_frame(frame, state) do
    case Plushie.Protocol.decode_message(frame, :msgpack) do
      {:hello, _} ->
        PlushiePad.Shared.connect(state.shared, state.client_id)
        %{state | handshake_done: true}

      %WidgetEvent{} = event ->
        if state.handshake_done,
          do: PlushiePad.Shared.event(state.shared, event)

        state

      _ ->
        state
    end
  end

  defp send_snapshot(model, state) do
    tree = PlushiePad.view(model) |> Plushie.Tree.normalize()
    data = Plushie.Protocol.encode_snapshot(tree, :msgpack)
    send_packet(state, data)
  end

  defp send_packet(state, data) do
    packet = Framing.encode_packet(data) |> IO.iodata_to_binary()
    :ssh_connection.send(state.conn, state.channel, packet)
  end
end
```

The handshake is simple: we send settings, the renderer replies with
`{:hello, _}`, and we register with the shared GenServer. From then
on, every model change triggers a full snapshot to the client. Cleanup
happens in `terminate/2`, which is called for all shutdown paths.

## SSH server with key authentication

The server uses Erlang's built-in `:ssh` daemon. On first start, it
generates an Ed25519 host key (using `ssh-keygen` if available,
falling back to Erlang's `:public_key` module). Client authentication
uses the user's existing SSH keys via `~/.ssh/authorized_keys`:

```elixir
defmodule PlushiePad.SshServer do
  def start(shared, port \\ 2222) do
    :ok = Application.ensure_started(:crypto)
    :ok = Application.ensure_started(:asn1)
    :ok = Application.ensure_started(:public_key)
    :ok = Application.ensure_started(:ssh)

    system_dir = ensure_host_key()
    user_dir = Path.expand("~/.ssh")

    {:ok, _} =
      :ssh.daemon({127, 0, 0, 1}, port,
        system_dir: String.to_charlist(system_dir),
        user_dir: String.to_charlist(user_dir),
        auth_methods: ~c"publickey",
        subsystems: [{~c"plushie", {PlushiePad.SshChannel, [shared]}}]
      )

    IO.puts("SSH server listening on localhost:#{port}")
  end

  defp ensure_host_key do
    dir = Path.join(["priv", "ssh"])
    File.mkdir_p!(dir)
    key_file = Path.join(dir, "ssh_host_ed25519_key")

    unless File.exists?(key_file) do
      case System.find_executable("ssh-keygen") do
        nil -> generate_key_erlang(key_file)
        _ -> System.cmd("ssh-keygen", ["-t", "ed25519", "-f", key_file, "-N", "", "-q"])
      end

      IO.puts("Generated SSH host key: #{key_file}")
    end

    dir
  end

  defp generate_key_erlang(path) do
    key = :public_key.generate_key({:namedCurve, :ed25519})
    pem = :public_key.pem_encode([:public_key.pem_entry_encode(:ECPrivateKey, key)])
    File.write!(path, pem)
  end
end
```

The host key persists in `priv/ssh/` so the server identity is stable
across restarts. Clients authenticate with their existing SSH keys --
no passwords, no extra configuration.

## Starting the server

Add a mix task to start everything:

```elixir
defmodule Mix.Tasks.PlushiePad.Server do
  use Mix.Task

  def run(_args) do
    Mix.Task.run("app.start")
    {:ok, shared} = PlushiePad.Shared.start_link()
    PlushiePad.SshServer.start(shared)
    Process.sleep(:infinity)
  end
end
```

## Connecting

Start the server in one terminal:

```bash
mix plushie_pad.server
```

Connect from another terminal using the Plushie renderer over SSH:

```bash
plushie --exec "ssh -p 2222 localhost -s plushie"
```

Open a third terminal and connect again. Both windows show the same
pad. Edit an experiment in one window and click Save. The other
window updates instantly.

This is the same wire protocol, the same renderer binary, the same
`view/1` function. The only difference is the transport: SSH instead
of stdio. Your Elixir code runs on the server; the renderer runs
wherever there is a screen.

## Verify it

The shared GenServer is a plain GenServer that can be tested without
SSH:

```elixir
test "shared server broadcasts model changes" do
  {:ok, shared} = PlushiePad.Shared.start_link()
  PlushiePad.Shared.connect(shared, "test-client")

  PlushiePad.Shared.event(shared, %WidgetEvent{type: :click, id: "save"})

  assert_receive {:model_changed, model}
  assert model.preview != nil
end
```

---

You now have a collaborative editor with file management, styling,
animation, subscriptions, effects, canvas drawing, custom widgets,
tests, and shared state over SSH. The
[reference docs](../reference/built-in-widgets.md) cover each topic
in depth when you need it.