Sofa.Session (sofa v0.8.1)

Copy Markdown View Source

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)

Summary

Types

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

Functions

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).

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.

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.

Types

error()

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

info()

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

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

Functions

info(sofa)

@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(sofa, name, password)

@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(sofa)

@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.