# `NervesGate.Network`

Ethernet and Internet uplink configuration with protected trials and rollback.

## Commands

`propose/4` applies settings temporarily and returns `{:ok, trial_id}`.
`confirm/2` saves that trial; `cancel/2` restores saved settings. Both return
`:ok` after completion. Rejected or failed commands return `{:error, reason}`.
Manual trials expire after 60 seconds. First setup through verified USB may
auto-save within 15 seconds. A caller timeout does not cancel admitted work.

## Queries and notifications

`validate/1`, `ready?/2` and `conflicts/2` are pure checks. `status/1` reads the
current trial, settings and interfaces. Subscribe with `observe/1` before
reading; notifications are hints to read again, not complete status maps.

The server argument defaults to this module. VintageNet owns saved settings.
Failed restoration sets `:network_restore_failed`; successful restoration clears it.

# `cancel`

```elixir
@spec cancel(String.t(), GenServer.server()) :: :ok | {:error, term()}
```

Cancel the matching trial. Replies after saved settings have been restored.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `confirm`

```elixir
@spec confirm(String.t(), GenServer.server()) :: :ok | {:error, term()}
```

Save the matching, unexpired trial after checking current readiness. Replies after saving.

# `conflicts`

```elixir
@spec conflicts(map() | nil, map()) :: list()
```

List observed subnet conflicts for these settings without performing I/O.

# `observe`

```elixir
@spec observe(GenServer.server()) :: :ok | {:error, :unavailable}
```

Subscribe the caller to network workflow and adapter properties; read status afterward.

# `propose`

```elixir
@spec propose(map(), GenServer.server(), map() | nil, map() | :any) ::
  {:ok, String.t()} | {:error, term()}
```

Apply a temporary trial and return its ID after application.

Immediately-ready first USB setup waits for auto-save before replying. If still
settling, it returns a pending trial. `access` must come from trusted server
observations of both socket endpoints, never user input; omit it for manual setup.
Supply `expected` to reject a draft if the saved network settings have changed.

# `ready?`

```elixir
@spec ready?(map() | nil, map()) :: boolean()
```

Check that observed topology/settings match the proposal, without subnet conflicts.

# `status`

```elixir
@spec status(GenServer.server()) :: map()
```

Read config, trial, observed interfaces, phase, readiness, recovery and the last error.

# `validate`

```elixir
@spec validate(map()) :: {:ok, map()} | {:error, term()}
```

Validate and normalize string-keyed settings without reading or changing hardware.

---

*Consult [api-reference.md](api-reference.md) for complete listing*