thinwrap_notifications_error (thinwrap_notifications v1.2.0)

View Source

Builders for thinwrap_notifications:connector_error/0, the plain map every send failure is returned as.

Connectors build errors here and fail/1 them; the public thinwrap_notifications functions catch that and return {error, Error}. Misuse of the API (a missing config key, a provider on the wrong channel) is not a connector error: it raises badarg.

There is deliberately no retry_after_seconds key: for a vendor HTTP error the raw Retry-After header rides in cause as <<"retryAfter">> and its parsed seconds as <<"retryAfterSeconds">>, next to the decoded body under <<"raw">> — the {raw, retryAfter?, retryAfterSeconds?} cause shape shared with the sibling libraries.

Summary

Types

code()

Functions

assert_webhook_https(Url, Provider)

Reject a non-https webhook URL. For chat connectors whose webhook URL IS the credential, cleartext http would leak the token, so a stale or typo'd config fails closed rather than transmitting it.

codes()

Every code() value, in declaration order.

fail(Error)

Abort the current send with Error. Only valid inside a call made through thinwrap_notifications, which turns it into {error, Error}.

invalid_request(Msg)

A pre-flight invalid_request (no HTTP round-trip).

new(Code, Fields)

Build an error. Fields may carry status, provider_message, message and cause; message falls back to provider_message, then to <<"Connector error">>, so it is always present. undefined values are dropped: an absent optional key is omitted, never undefined.

parse_retry_after(Value)

Parse a Retry-After header: a non-negative count of seconds, or an HTTP-date (seconds from now, floored at 0). undefined when unparseable or negative.

vendor_error(Status, Headers, Raw, Code, ProviderMsg)

The error for a non-2xx response (or a 2xx the connector re-classifies). The vendor-to-code classification and the message are the connector's; this adds the shared Retry-After surfacing. An empty message becomes <<"<no vendor message>">>.

Types

code()

-type code() ::
          invalid_recipient | rate_limited | auth_failed | provider_unavailable | invalid_request |
          unknown.

Functions

assert_webhook_https(Url, Provider)

-spec assert_webhook_https(binary(), binary()) -> ok.

Reject a non-https webhook URL. For chat connectors whose webhook URL IS the credential, cleartext http would leak the token, so a stale or typo'd config fails closed rather than transmitting it.

codes()

-spec codes() -> [code()].

Every code() value, in declaration order.

fail(Error)

-spec fail(thinwrap_notifications:connector_error()) -> no_return().

Abort the current send with Error. Only valid inside a call made through thinwrap_notifications, which turns it into {error, Error}.

invalid_request(Msg)

-spec invalid_request(binary()) -> thinwrap_notifications:connector_error().

A pre-flight invalid_request (no HTTP round-trip).

new(Code, Fields)

-spec new(code(), map()) -> thinwrap_notifications:connector_error().

Build an error. Fields may carry status, provider_message, message and cause; message falls back to provider_message, then to <<"Connector error">>, so it is always present. undefined values are dropped: an absent optional key is omitted, never undefined.

parse_retry_after(Value)

-spec parse_retry_after(binary()) -> non_neg_integer() | undefined.

Parse a Retry-After header: a non-negative count of seconds, or an HTTP-date (seconds from now, floored at 0). undefined when unparseable or negative.

vendor_error(Status, Headers, Raw, Code, ProviderMsg)

-spec vendor_error(integer(),
                   thinwrap_notifications_transport:headers(),
                   term(),
                   code(),
                   binary() | undefined) ->
                      thinwrap_notifications:connector_error().

The error for a non-2xx response (or a 2xx the connector re-classifies). The vendor-to-code classification and the message are the connector's; this adds the shared Retry-After surfacing. An empty message becomes <<"<no vendor message>">>.