CalDAVEx.Config (CalDAVEx v0.2.1)

Configuration for a CalDAVEx.Client.

Holds the server base URL, authentication tuple, User-Agent string, and HTTP request timeout. Build configs with new/2 and refine them with the with_* helpers. The top-level CalDAVEx module exposes thin wrappers around these functions for the common case.

Summary

Types

auth()

Authentication configuration.

t()

CalDAV client configuration struct.

Functions

default_user_agent()

Returns the library's default User-Agent string.

new(base_url, auth)

Builds a new configuration.

with_timeout(cfg, ms)

Returns a copy of cfg with the given request timeout in milliseconds.

with_user_agent(cfg, ua)

Returns a copy of cfg with the given User-Agent string.

Types

auth()

@type auth() :: :no_auth | {:basic, String.t(), String.t()} | {:bearer, String.t()}

Authentication configuration.

:no_auth - no authentication header
{:basic, username, password} - HTTP Basic
{:bearer, token} - Bearer token

t()

@type t() :: %CalDAVEx.Config{
  auth: auth(),
  base_url: String.t(),
  timeout_ms: non_neg_integer(),
  user_agent: String.t() | nil
}

CalDAV client configuration struct.

Functions

default_user_agent()

@spec default_user_agent() :: String.t()

Returns the library's default User-Agent string.

Derived at runtime from the loaded application spec (:application.get_key(:caldav_ex, :vsn)), so it always matches the released package version. Falls back to "caldav_ex" if the application spec is not loaded (e.g. during compilation of the library itself).

Returns

the default User-Agent string (e.g. "caldav_ex/0.2.1")

new(base_url, auth)

@spec new(String.t(), auth()) :: t()

Builds a new configuration.

The trailing slash on base_url is stripped so that downstream URL joining is unambiguous.

Parameters

base_url - the CalDAV server base URL (must be a binary)
auth - an authentication tuple from CalDAVEx.basic_auth/2, CalDAVEx.bearer_auth/1, or CalDAVEx.no_auth/0

Examples

CalDAVEx.Config.new(
  "https://caldav.example.com/",
  CalDAVEx.basic_auth("user", "pass")
)

with_timeout(cfg, ms)

@spec with_timeout(t(), non_neg_integer()) :: t()

Returns a copy of cfg with the given request timeout in milliseconds.

The timeout is passed to the underlying HTTP client as receive_timeout.

Parameters

cfg - an existing %CalDAVEx.Config{}
ms - timeout in milliseconds (must be a non-negative integer)

Returns

the updated %CalDAVEx.Config{} struct

Examples

config |> CalDAVEx.Config.with_timeout(30_000)

with_user_agent(cfg, ua)

@spec with_user_agent(t(), String.t()) :: t()

Returns a copy of cfg with the given User-Agent string.

Parameters

cfg - an existing %CalDAVEx.Config{}
ua - the User-Agent string to send on every request

Returns

the updated %CalDAVEx.Config{} struct

Examples

config |> CalDAVEx.Config.with_user_agent("MyApp/1.0")