Crate honk_me 

The official Rust client for Honk: send events from your apps, jobs, scripts and CI to your phone, as calm, grouped push notifications.

• Async-first on Tokio and reqwest with rustls (no OpenSSL); a synchronous blocking::Honk with the feature blocking.
• Every send carries an Idempotency-Key (yours, or a UUIDv7) that is reused on every retry, so a retry never creates a duplicate.
• Retries only network errors, timeouts, 429 and 5xx, with exponential backoff and full jitter, never sooner than Retry-After, all under a total deadline (30 s). Redirects are reported, never followed.
• Local validation of everything cheap (lengths, URLs, actions, metadata, the 16 KiB body), with every invalid field reported at once. HonkBuilder::validate(false) leaves it to the server.

Keep the ingestion key (honk_…) on the server: never ship it inside a client app.

Quick start

use honk_me::{Honk, Message, Severity};

#[tokio::main]
async fn main() -> honk_me::Result<()> {
    let honk = Honk::from_env()?; // HONK_URL, HONK_KEY

    // The Honk scale: light, beep, loud, long, blast.
    honk.beep("Backup finished", "nightly pg_dump took 42 s").await?;

    // Every field, and your own idempotency key.
    let msg = Message::new("Ana asked for a quote: 3 rooms, 2 bathrooms")
        .title("New quote request")
        .severity(Severity::LOUD)
        .group_key("requests/4812")
        .url("https://shop.example.com/admin/requests/4812")
        .metadata("rooms", 3);
    let accepted = honk.send(&msg, "request-4812").await?;
    println!("stored as {}", accepted.id);

    // Incidents: a problem opens one for its group, a recovery closes it.
    honk.problem("db/backup", "Backup failed", "pg_dump exited with 1").await?;
    honk.recovery("db/backup", "Backup OK", "pg_dump finished").await?;
    Ok(())
}

Errors

Every failure is an Error: Validation (fix the message), Auth, Quota, Conflict, Network, Timeout, Server or Http, each with a Failure holding the details. Error::is_retryable tells whether sending again later (with the same idempotency key) may succeed.

Features

• blocking: blocking::Honk, a synchronous client on a private Tokio runtime.

Modules

blockingblocking

A synchronous client (feature blocking), for scripts, CLIs and code without an async runtime. It wraps the async Honk on a private single-threaded Tokio runtime, so it has the same retries, deadline, idempotency and validation.

Structs

Accepted

The 202 answer: the message is durably stored. It does not mean pushed, delivered or read.

Action

A button on a message. Honk never opens the URL; the phone does, when you tap the button.

Defaults

Values applied to every message that leaves these fields unset.

Failure

The details of a failed send.

FieldError

One invalid field, from the server (error.fields[]) or local validation.

Honk

Sends messages to one Honk project. Cheap to clone (the connection pool is shared); create one per application and reuse it so connections are kept alive. Needs a Tokio runtime; see blocking::Honk (feature blocking) for synchronous code.

HonkBuilder

Configures a Honk client. URL and key are required; everything else has a default.

Message

One event for POST /v1/messages. Only the message text is required; unset fields are omitted so the server defaults apply (severity info, priority normal, source api, environment default, channel general, event type event, TTL 3600 s). Empty strings count as unset.

ParseEnumError

The error of Severity::from_str and the other enums’ from_str: names the valid values.

PendingSend

A send prepared by a helper (Honk::loud, Honk::problem, …). Chain more fields, then .await it (or call send).

Enums

Category

The category (taxonomy v1).

Error

Everything that can go wrong. Every variant except InvalidConfiguration carries a Failure with the details (status, API error code, field errors, the idempotency key that was used, attempts, …).

EventType

A problem opens an incident for its group, a recovery closes it. Both need a group key.

MetadataValue

A metadata value: a string, a number or a boolean.

Priority

The priority declared by the source. Urgent needs an ingestion key with allow_urgent (otherwise 403 priority_not_allowed).

Severity

Severity, lowest to highest. Error and Critical raise the effective priority to at least High. Every severity has a horn name on the Honk scale: Severity::LIGHT, Severity::BEEP, Severity::LOUD, Severity::LONG, Severity::BLAST.

Constants

MAX_ACTIONS

The most actions (buttons) on a message.

MAX_ACTION_TITLE

The longest action title, in characters.

MAX_BODY_BYTES

The largest JSON body Honk accepts: 16 KiB.

MAX_CHANNEL

The longest channel, in characters.

MAX_ENVIRONMENT

The longest environment, in characters.

MAX_GROUP_KEY

The longest group key, in characters.

MAX_MESSAGE_BYTES

The longest message text, in bytes of UTF-8.

MAX_METADATA_KEYS

The most metadata keys.

MAX_METADATA_STRING

The longest metadata string value, in characters.

MAX_SOURCE

The longest source, in characters.

MAX_TITLE

The longest title, in characters.

MAX_TTL_SECONDS

The longest push lifetime, in seconds.

MAX_URL_BYTES

The longest url, image_url or action URL, in bytes.

MIN_TTL_SECONDS

The shortest push lifetime, in seconds.

VERSION

The version of this crate, sent in the User-Agent header (honk-me-rust/<version>).

Functions

encode_message

Validates message (unless validate is false) with defaults applied and returns the exact JSON body that Honk::send posts. Useful for logging, dry runs and tests.

new_idempotency_key

A new UUIDv7 (RFC 9562: 48-bit Unix milliseconds, then random bits), the default Idempotency-Key. Store it with your job if you want to retry the same event across process restarts.

Type Aliases

Result

A Result whose error is honk_me::Error.