Skip to main content

Crate octo_notify

Crate octo_notify 

Source
Expand description

§octo-notify

A focused Rust client for the GitHub Notifications API: complete, typed coverage of every endpoint, plus a polling engine for building applications on the notifications inbox. It is not a general GitHub client.

§Layers

  1. Typed client (Client): every Notifications endpoint, conditional requests (If-Modified-Since / 304), rate-limit accounting, pagination, and forward-compatible models.
  2. App engine (Poller): the inbox as an async Stream of Events, with client-side filters.
  3. State (StateStore): dedupe across restarts.

Layers 2 and 3 need the stream feature, which is on by default.

§Authentication

The notifications inbox is user-scoped, so authentication is a single bearer token. A classic PAT needs the notifications scope (or repo to also read issue and commit subjects); a fine-grained PAT needs the read-only “Notifications” account permission.

use octo_notify::{Auth, Client};

let client = Client::new(Auth::from_env()?)?; // GITHUB_TOKEN or GH_TOKEN
let explicit = Client::new(Auth::token("ghp_example"))?;

Tokens come from a TokenProvider, so credentials that expire can refresh themselves. The token-refresh feature adds RefreshingToken for GitHub App user-to-server tokens. Override the base URL for GitHub Enterprise Server:

let client = Client::builder()
    .auth(Auth::from_env()?)
    .base_url("https://ghe.example.com/api/v3")
    .user_agent("my-app/1.0")
    .build()?;

§Listing notifications

client.notifications() lists the inbox; client.repo(owner, name).notifications() scopes to one repository. A single send() returns a Listing (which may be Listing::NotModified when the request is conditional); all() collects every page and stream() yields items across pages.

use octo_notify::{Auth, Client, Listing, Reason};

let client = Client::new(Auth::from_env()?)?;
let listing = client.notifications().list().participating(true).send().await?;
if let Listing::Modified(page) = listing {
    for n in &page.items {
        if matches!(n.reason, Reason::Mention) {
            println!("{} - {}", n.repository.full_name, n.subject.title);
        }
    }
}

§Threads and subscriptions

client.thread(id) operates on one thread: fetch it, mark it read or done (one-way), and manage its subscription.

let client = Client::new(Auth::from_env()?)?;
let thread = client.thread("123456789");
let notification = thread.get().await?;
thread.mark_read().await?;
thread.set_subscription(true).await?; // ignore future notifications

§Watching the inbox

Client::poller builds a Poller that yields an async stream of Events. By default it watches the whole inbox, obeys the server poll interval, and dedupes through an in-memory store. Filter by reason, subject type, repository, or a predicate.

use futures::StreamExt;
use octo_notify::app::Event;
use octo_notify::{Auth, Client, Reason};

let client = Client::new(Auth::from_env()?)?;
let mut events = Box::pin(client.poller().reasons([Reason::ReviewRequested]).build().stream());
while let Some(event) = events.next().await {
    match event? {
        Event::New(n) => println!("new: {}", n.subject.title),
        Event::Updated(n) => println!("updated: {}", n.subject.title),
    }
}

Persist state across restarts with the file-store feature and JsonFileStore:

ⓘ
use octo_notify::app::JsonFileStore;

let store = JsonFileStore::open("/var/cache/octo-notify.json")?;
let poller = client.poller().store(store).build();

§Robustness contract

  • Transient vs fatal errors: network blips, 5xx, and rate limits back off and retry; only fatal errors (for example 401) end the stream.
  • At-least-once delivery: events emit in ascending updated_at; per-thread seen state commits after delivery and the Last-Modified watermark advances only after the full tick, so a crash re-emits rather than drops. Dedupe downstream on (id, updated_at).
  • Pagination vs conditional requests: the If-Modified-Since check applies to page 1; on a change, all pages are fetched before classification, so the inbox is never half-read.
  • Shutdown: drop the stream, or pass a CancellationToken for cooperative shutdown.

§Bulk actions

Mark many threads read or done concurrently, with a bounded worker count and per-item results.

let client = Client::new(Auth::from_env()?)?;
let ids = [ThreadId::from("1"), ThreadId::from("2")];
for (id, result) in client.mark_done_each(ids, 8).await {
    if let Err(e) = result {
        eprintln!("{id}: {e}");
    }
}

§Errors and rate limits

Every fallible call returns Result. Error distinguishes API errors, primary and secondary rate limits (Error::RateLimited with RateLimitKind), authentication failures, and deserialization problems. A 304 is success, not an error: it surfaces as Listing::NotModified. With the retry feature, RetryPolicy makes one-shot calls wait out rate limits automatically.

§Feature flags

FeatureDefaultDescription
rustlsyesTLS via rustls
native-tlsnoTLS via the platform’s native stack
streamyesThe poller engine and stream() pagination
file-storenoJsonFileStore, file-backed state for cross-restart dedupe
sqlite-storenoSqliteStore, SQLite-backed state
token-refreshnoRefreshingToken for expiring credentials
retrynoRetryPolicy for auto-retrying rate-limited calls
tracingnoStructured tracing instrumentation of requests and the poller
clinoThe octo-notify command-line binary (cargo install octo-notify --features cli)

With the tracing feature on, install any tracing subscriber (for example tracing-subscriber) in your application to see request, rate-limit, and poller events.

Re-exports§

pub use auth::RefreshingToken;
pub use auth::Auth;
pub use auth::TokenProvider;
pub use endpoints::ListNotifications;
pub use endpoints::ListSubscriptions;
pub use endpoints::MarkAllRead;
pub use endpoints::NotificationsHandler;
pub use endpoints::RepoHandler;
pub use endpoints::RepoNotificationsHandler;
pub use endpoints::ThreadHandler;
pub use error::Error;
pub use error::RateLimitKind;
pub use error::Result;
pub use models::MinimalRepository;
pub use models::Notification;
pub use models::Reason;
pub use models::RepositorySubscription;
pub use models::SimpleUser;
pub use models::Subject;
pub use models::SubjectType;
pub use models::ThreadId;
pub use models::ThreadSubscription;
pub use pagination::Listing;
pub use pagination::NotModified;
pub use pagination::Page;
pub use rate_limit::RateLimit;

Modules§

app
Layer 2/3: the application engine.
auth
Authentication.
cli
The octo-notify command-line tool, built behind the cli feature.
endpoints
Typed endpoint handlers.
error
Error and result types for the crate.
models
Typed models for notification payloads.
pagination
Listing results, pagination, and conditional-request outcomes.
prelude
Common imports for downstream apps: use octo_notify::prelude::*;.
rate_limit
Rate-limit accounting parsed from response headers.

Structs§

Client
A client for the GitHub Notifications API.
ClientBuilder
Builder for Client.
RetryPolicy
Controls automatic retrying of rate-limited one-shot calls. Requires the retry feature.

Type Aliases§

SecretString
Secret string type.