webpush - v1.0.0

webpush/push

Types

Keys

</>

Represents the cryptographic keys used for authentication and encryption in a push subscription.

  • auth: The authentication secret as a base64url-encoded string.
  • p256dh: The user’s public key as a base64url-encoded string.
pub type Keys {
  Keys(auth: String, p256dh: String)
}

Constructors 

  • Keys(auth: String, p256dh: String)

Options

</>

Options for sending a push notification.

  • ttl: Time to live for the push message in seconds.
  • subscriber: The subscriber’s contact information (e.g., email).
  • vapid_public_key_b64url: VAPID public key as a base64url-encoded string.
  • vapid_private_key_b64url: VAPID private key as a base64url-encoded string.
  • topic: Optional topic for the push message.
  • urgency: Optional urgency level for the push message.
  • record_size: Optional maximum record size for the push message.
  • vapid_expiration_unix: Optional VAPID token expiration time as a Unix timestamp.
pub type Options {
  Options(
    ttl: Int,
    subscriber: String,
    vapid_public_key_b64url: String,
    vapid_private_key_b64url: String,
    topic: option.Option(String),
    urgency: option.Option(urgency.Urgency),
    record_size: option.Option(Int),
    vapid_expiration_unix: option.Option(Int),
  )
}

Constructors

PushError

</>

Represents the possible errors that can occur during the push notification process.

  • DecodeKeyError: Indicates a failure to decode a cryptographic key.
  • InvalidPeerPublicKey: The provided peer public key is in an invalid format.
  • CryptoError(String): A cryptographic operation failed, with an associated error message.
  • HttpError(String): An HTTP request or response error, with an associated error message.
  • VapidHeaderError(vapid.VapidError): An error occurred while handling the VAPID header.
  • MaxPadExceeded: The payload size has exceeded the allowed maximum length.
pub type PushError {
  DecodeKeyError
  InvalidPeerPublicKey
  CryptoError(String)
  HttpError(String)
  VapidHeaderError(vapid.VapidError)
  MaxPadExceeded
}

Constructors 

  • DecodeKeyError
  • InvalidPeerPublicKey
  • CryptoError(String)
  • HttpError(String)
  • VapidHeaderError(vapid.VapidError)
  • MaxPadExceeded

Subscription

</>

Represents a push subscription, including the endpoint and associated keys.

  • endpoint: The URL to which push messages are sent.
  • keys: The cryptographic keys for the subscription.
pub type Subscription {
  Subscription(endpoint: String, keys: Keys)
}

Constructors 

  • Subscription(endpoint: String, keys: Keys)

Values

max_record_size

</> 
pub const max_record_size: Int

The maximum allowed size for a record in bytes.

push_error_to_string

</> 
pub fn push_error_to_string(error: PushError) -> String

Converts a PushError value into a human-readable string description.

This function matches on the provided PushError and returns a descriptive error message for each variant, including decoding errors, cryptographic errors, HTTP errors, VAPID header errors, and payload length issues.

  • DecodeKeyError: Indicates a failure to decode a key.
  • InvalidPeerPublicKey: Indicates an invalid peer public key format.
  • CryptoError(msg): Indicates a cryptographic error with a message.
  • HttpError(msg): Indicates an HTTP error with a message.
  • VapidHeaderError(vapid_err): Indicates a VAPID header error, with details from vapid_error_to_string.
  • MaxPadExceeded: Indicates the payload has exceeded the maximum allowed length.

Returns: A string describing the error.

send_notification

</> 
pub fn send_notification(
  message: BitArray,
  sub: Subscription,
  opts: Options,
) -> Result(response.Response(BitArray), PushError)

Sends a web push notification to a subscriber.

This function performs the following steps:

  1. Decodes the authentication and peer public keys from the subscription.
  2. Validates the peer public key format (must be uncompressed).
  3. Encrypts the payload using the provided keys and record size.
  4. Generates a VAPID authorization header for authentication.
  5. Constructs an HTTP request with the appropriate headers and binary body.
  6. Sends the request and returns the response or an error.

Arguments

  • message: The payload to send as a BitArray.
  • sub: The subscription information containing endpoint and keys.
  • opts: Options for the push notification, such as TTL, topic, urgency, and VAPID keys.

Returns

  • Ok(response.Response(BitArray)): The HTTP response on success.
  • Error(PushError): An error if any step fails (e.g., invalid keys, encryption, HTTP).
✨ Search Document