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
- Typed client (
Client): every Notifications endpoint, conditional requests (If-Modified-Since/304), rate-limit accounting, pagination, and forward-compatible models. - App engine (
Poller): the inbox as an asyncStreamofEvents, with client-side filters. - 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 theLast-Modifiedwatermark 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-Sincecheck 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
CancellationTokenfor 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
| Feature | Default | Description |
|---|---|---|
rustls | yes | TLS via rustls |
native-tls | no | TLS via the platform’s native stack |
stream | yes | The poller engine and stream() pagination |
file-store | no | JsonFileStore, file-backed state for cross-restart dedupe |
sqlite-store | no | SqliteStore, SQLite-backed state |
token-refresh | no | RefreshingToken for expiring credentials |
retry | no | RetryPolicy for auto-retrying rate-limited calls |
tracing | no | Structured tracing instrumentation of requests and the poller |
cli | no | The 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-notifycommand-line tool, built behind theclifeature. - 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.
- Client
Builder - Builder for
Client. - Retry
Policy - Controls automatic retrying of rate-limited one-shot calls. Requires the
retryfeature.
Type Aliases§
- Secret
String - Secret string type.