git_lfs_api/
lib.rs

1//! HTTP client for the Git LFS batch and locking APIs.
2//!
3//! Git LFS speaks to a server over HTTPS using two endpoints.
4//! The batch endpoint (`POST /objects/batch`) takes a list of
5//! OIDs and sizes and returns one transfer URL per object
6//! (plus any auth headers and an expiry window); the locking
7//! endpoint suite (`/locks`, `/locks/verify`,
8//! `/locks/{id}/unlock`, …) lets clients claim files to
9//! coordinate edits across users. See the [batch spec][batch]
10//! and [locking spec][locking] for the wire-protocol contract.
11//!
12//! [`Client`] is the entry point. Construct one per endpoint
13//! URL with an initial [`Auth`] (None, Basic, or Bearer),
14//! optionally attach a credential helper via
15//! [`Client::with_credential_helper`] and an [`SshResolver`]
16//! via [`Client::with_ssh_resolver`], then invoke the
17//! per-operation methods. `Client` is cheap to clone and shares
18//! an underlying connection pool.
19//!
20//! Request and response types are split by operation. Batch
21//! uses [`BatchRequest`] and [`BatchResponse`], with
22//! [`ObjectResult`] carrying either [`Actions`] or an
23//! [`ObjectError`] per object. Lock operations use
24//! [`CreateLockRequest`], [`ListLocksFilter`],
25//! [`VerifyLocksRequest`], and [`DeleteLockRequest`], with
26//! [`Lock`], [`Owner`], and [`Ref`] as the shared model types.
27//!
28//! On a 401 the client queries the attached credential helper,
29//! retries once, and reports `approve` or `reject` based on the
30//! outcome. Successful fills are cached for the lifetime of the
31//! `Client`. SSH-mediated endpoints (via [`SshResolver`]) can
32//! swap in a replacement HTTPS URL and auth headers per request.
33//!
34//! Failures surface as [`ApiError`], with predicates
35//! ([`is_unauthorized`](ApiError::is_unauthorized),
36//! [`is_retryable`](ApiError::is_retryable), …) for dispatch
37//! without matching on the variant. Server-supplied
38//! `Retry-After` (on 429 or 5xx responses) reaches callers via
39//! [`ApiError::retry_after`]; [`parse_retry_after`] is exported
40//! for reuse on other response paths.
41//!
42//! Byte transfer against action URLs lives in
43//! [`git-lfs-transfer`][transfer-crate]; credential resolution
44//! lives in [`git-lfs-creds`][creds-crate]; server URL
45//! discovery from a git remote lives in
46//! [`git-lfs-git`][git-crate].
47//!
48//! [batch]: https://gitlab.com/rustutils/git-lfs/-/blob/master/docs/api/batch.md
49//! [locking]: https://gitlab.com/rustutils/git-lfs/-/blob/master/docs/api/locking.md
50//! [transfer-crate]: https://docs.rs/git-lfs-transfer
51//! [creds-crate]: https://docs.rs/git-lfs-creds
52//! [git-crate]: https://docs.rs/git-lfs-git
53
54// ApiError::Status carries enough context (URL, body, LFS-Authenticate,
55// Retry-After) that it crosses clippy's default 128-byte threshold for
56// the Err arm. Boxing the variant would cascade through every match
57// site; for an error type used only on failure paths the size is not
58// worth chasing.
59#![allow(clippy::result_large_err)]
60
61mod auth;
62mod batch;
63mod client;
64mod error;
65mod locks;
66mod models;
67mod ssh;
68
69pub use auth::Auth;
70pub use batch::{
71    Action, Actions, BatchRequest, BatchResponse, ObjectError, ObjectResult, ObjectSpec, Operation,
72};
73pub use client::Client;
74pub use error::{ApiError, ServerError, parse_retry_after};
75pub use locks::{
76    CreateLockError, CreateLockRequest, DeleteLockRequest, ListLocksFilter, LockList,
77    VerifyLocksRequest, VerifyLocksResponse,
78};
79pub use models::{Lock, Owner, Ref};
80pub use ssh::{SharedSshResolver, SshAuth, SshOperation, SshResolver};
git_lfs_api/lib.rs

git_lfs_api/
lib.rs
