# `Macaw.Layers.Url.Policy`
[🔗](https://github.com/dcoai/macaw_layers/blob/v0.4.0/lib/macaw/layers/url/policy.ex#L1)

A host's URL policy (spec/01 §8.3): which URLs a document read on this host may use.
The host knows where its documents come from and what its pages may load, so the policy
is its intent, built once and passed as a value to the reads it makes
(`Macaw.Layers.Form.read/3`'s `urls:`). It is never application config, and never part
of a document's value: a document is well formed everywhere (`Macaw.Layers.Url`), and
allowed or not by the host that reads it.

**Closed by default.** `new([])` allows nothing; each scheme, host and data type is
allowed only by being named.

    iex> policy = Macaw.Layers.Url.Policy.new(schemes: ["https"], hosts: ["tiles.example"])
    iex> {:ok, url} = Macaw.Layers.Url.new("https://tiles.example/{z}/{x}/{y}.png")
    iex> Macaw.Layers.Url.Policy.allows(policy, url)
    :ok
    iex> {:ok, url} = Macaw.Layers.Url.new("javascript:alert(1)")
    iex> Macaw.Layers.Url.Policy.allows(policy, url)
    {:error, :scheme}

**Bounded.** Only `https`, `http` and `data` can be allowed, and `data` only as an image of
`image/png`, `image/jpeg` or `image/webp`: `image/svg+xml` can carry script. Naming any
other raises `ArgumentError`, so the loosest policy a host can write is "https and http
to any host, and those images".

Ported from visualize's `Visualize.Chart.Urls` (its spec/14 §10.3), whose default
(https to any host) a host now writes out if it wants it.

# `reason`

```elixir
@type reason() :: :scheme | :http | :data_type | :host
```

Why a policy refuses a URL: `:scheme`, a scheme it does not allow; `:http`, `http:` where
it allows only `https:`; `:data_type`, a `data:` URL of a type it does not allow; `:host`,
a host (or, for a `{s}` host, any of its subdomains' hosts) it does not list.

# `t`

```elixir
@type t() :: %Macaw.Layers.Url.Policy{
  data: [String.t()],
  hosts: :any | [String.t()],
  schemes: [String.t()]
}
```

The schemes, the hosts (`:any`, or hosts and `*.domain`) and the data types allowed.

# `allows`

```elixir
@spec allows(t(), Macaw.Layers.Url.t()) :: :ok | {:error, reason()}
```

Whether the policy allows the URL: `:ok`, or `{:error, reason}`. A URL is read as
`Macaw.Layers.Url` reads it, from its text, so a struct built around `Url.new/2` is
judged as its text is.

# `check`

```elixir
@spec check(term(), t()) :: [Macaw.Layers.Fault.t()]
```

Every URL the value holds that the policy refuses, `{path, {:url, reason}}` by path from
the value, ordered: its maps, lists, tuples and structs are walked, so a URL is found wherever
any type holds one. A fault names the reason and never the URL.

    iex> {:ok, url} = Macaw.Layers.Url.new("http://a.example/")
    iex> Macaw.Layers.Url.Policy.check(%{marks: [%{url: url}]}, Macaw.Layers.Url.Policy.new(schemes: ["https"], hosts: :any))
    [{[:marks, 0, :url], {:url, :http}}]

# `narrow`

```elixir
@spec narrow(t(), keyword()) :: t()
```

The policy made stricter by `opts`, written as `new/1` takes them: each key given keeps
only what both allow, and a key not given keeps the policy's. A read can be stricter than
its host, never looser: a host the policy does not cover, or a scheme it does not allow,
is dropped, never added.

    iex> host = Macaw.Layers.Url.Policy.new(schemes: ["https", "http"], hosts: ["*.example"])
    iex> Macaw.Layers.Url.Policy.narrow(host, schemes: ["https", "data"], hosts: ["a.example", "b.test"])
    %Macaw.Layers.Url.Policy{schemes: ["https"], hosts: ["a.example"], data: []}

# `new`

```elixir
@spec new(keyword()) :: t()
```

The policy that allows exactly what it names:

- `schemes:` a list drawn from `"https"`, `"http"` and `"data"`;
- `hosts:` `:any`, or a list of hosts (`"tiles.example"`, an IPv6 literal in brackets)
  and `"*.domain"`, any host under the domain, matched without regard to case;
- `data:` a list drawn from `"image/png"`, `"image/jpeg"` and `"image/webp"`, the types a
  `data:` URL may have. It needs `"data"` among the schemes, and `"data"` needs it.

Each defaults to `[]`. An unknown key, a scheme or a data type outside its set, a host
that is not one, `data:` types without the `data` scheme, or the reverse, raises
`ArgumentError`.

    iex> Macaw.Layers.Url.Policy.new([])
    %Macaw.Layers.Url.Policy{schemes: [], hosts: [], data: []}
    iex> Macaw.Layers.Url.Policy.new(schemes: ["https"], data: ["image/svg+xml"])
    ** (ArgumentError) data: an allowed type is one of "image/png", "image/jpeg", "image/webp", got "image/svg+xml"

---

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