# `Sofa.Session`
[🔗](https://github.com/skunkwerks/sofa/blob/0.8.1/lib/sofa/session.ex#L1)

Cookie sessions, via `_session`: log in once and send a cookie instead
of credentials on every request.

> If the only tool you have is CouchDB, then
> everything looks like `{:ok, :relax}`

See https://docs.couchdb.org/en/stable/api/server/authn.html. Besides
sparing the server a password check per request, a session is how to
avoid CouchDB 3's account lockout after repeated failed logins: one
`login/3` either succeeds or fails, rather than every request failing.

## Examples

    {:ok, sofa} = Sofa.init("http://localhost:5984/") |> Sofa.client() |> Sofa.Session.login("jan", "apple")
    Sofa.Session.info(sofa)
    #=> {:ok, %{name: "jan", roles: ["users"], authenticated: "cookie"}}

    {:ok, sofa} = Sofa.Session.logout(sofa)

# `error`

```elixir
@type error() :: Sofa.Response.error() | term()
```

# `info`

```elixir
@type info() :: %{
  name: String.t() | nil,
  roles: [String.t()],
  authenticated: String.t() | nil
}
```

Who the server takes the client for, from `GET /_session`

# `info`

```elixir
@spec info(Sofa.t()) :: {:ok, info()} | {:error, error()}
```

Who the server takes the client for: the user name (`nil` when
anonymous), roles, and how it was authenticated (`"cookie"`,
`"default"` for basic auth, or `nil`).

# `login`

```elixir
@spec login(Sofa.t(), String.t(), String.t()) :: {:ok, Sofa.t()} | {:error, error()}
```

Logs in with a name and password, and returns the handle with the
session cookie set on its client and basic auth credentials removed,
so every further request is authenticated by the cookie.

# `logout`

```elixir
@spec logout(Sofa.t()) :: {:ok, Sofa.t()} | {:error, error()}
```

Ends the session, and returns the handle without the cookie. As the
docs note, the server keeps no session state, so this only forgets the
cookie on the client side.

---

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