pub struct GitHubService {
pub client: GitHubClient,
/* private fields */
}Expand description
High-level service for GitHub API operations.
GitHubService is the main entry point for interacting with the GitHub API.
It provides a simple, ergonomic interface with automatic fallback from GraphQL
to REST API when needed.
§Authentication
The service automatically detects the GITHUB_TOKEN environment variable.
Token permissions control access. Quotas vary by API resource and token type.
§Example
use github_rust::GitHubService;
let service = GitHubService::new()?;
// Check authentication status
if service.has_token() {
println!("Authenticated with higher rate limits");
}
// Get repository information
let repo = service.get_repository_info("rust-lang", "rust").await?;
println!("{} has {} stars", repo.name_with_owner, repo.stargazer_count);Fields§
§client: GitHubClientThe underlying HTTP client with connection pooling.
Implementations§
Source§impl GitHubService
impl GitHubService
Sourcepub fn new() -> Result<Self>
pub fn new() -> Result<Self>
Creates a new GitHub service with default configuration.
Automatically detects GITHUB_TOKEN from environment variables.
§Errors
Returns an error if the HTTP client cannot be initialized (rare, typically indicates system-level TLS or network configuration issues).
§Example
use github_rust::GitHubService;
let service = GitHubService::new()?;Sourcepub fn with_client(client: GitHubClient) -> Self
pub fn with_client(client: GitHubClient) -> Self
Creates a GitHub service with a custom client.
Useful for testing or when you need custom HTTP configuration.
Sourcepub fn with_fallback_policy(self, policy: FallbackPolicy) -> Self
pub fn with_fallback_policy(self, policy: FallbackPolicy) -> Self
Selects which authenticated GraphQL failures may trigger REST. Anonymous repository lookups always use REST directly.
Sourcepub async fn get_repository_info(
&self,
owner: &str,
name: &str,
) -> Result<Repository>
pub async fn get_repository_info( &self, owner: &str, name: &str, ) -> Result<Repository>
Fetches detailed information about a GitHub repository.
Uses REST directly without a token. Authenticated lookups use GraphQL, with REST fallback only for HTTP 502/503/504 by default. Authentication, permission, quota and decoding errors are returned unchanged.
§Arguments
owner- Repository owner (username or organization)name- Repository name
§Returns
Full repository details including stars, forks, language, topics, license, etc.
§Errors
GitHubError::NotFoundError- Repository doesn’t exist or is private without authGitHubError::RateLimitError- API rate limit exceededGitHubError::AccessBlockedError- Repository access blocked by GitHubGitHubError::DmcaBlockedError- Repository blocked for legal reasons
§Example
let service = GitHubService::new()?;
let repo = service.get_repository_info("microsoft", "vscode").await?;
println!("Name: {}", repo.name_with_owner);
println!("Stars: {}", repo.stargazer_count);
println!("Forks: {}", repo.fork_count);
if let Some(lang) = &repo.primary_language {
println!("Language: {}", lang.name);
}Sourcepub async fn search_repositories(
&self,
days_back: u32,
limit: usize,
language: Option<&str>,
min_stars: u32,
) -> Result<Vec<SearchRepository>>
pub async fn search_repositories( &self, days_back: u32, limit: usize, language: Option<&str>, min_stars: u32, ) -> Result<Vec<SearchRepository>>
Searches for recently created repositories with filtering options.
Finds repositories created within the specified time period, filtered by language and minimum star count. Results are sorted by stars (descending).
§Arguments
days_back- Search for repos created in the last N dayslimit- Maximum number of results (capped at 1000)language- Optional programming language filter (e.g., “rust”, “python”, “C++”)min_stars- Minimum number of stars required
§Errors
GitHubError::InvalidInput- Invalid language parameterGitHubError::RateLimitError- API rate limit exceededGitHubError::AuthenticationError- Token required for this operation
§Example
let service = GitHubService::new()?;
// Find Rust repos created in last 30 days with 50+ stars
let repos = service.search_repositories(
30, // days back
100, // limit
Some("rust"), // language
50, // min stars
).await?;
for repo in repos {
println!("{}: {} stars", repo.name_with_owner, repo.stargazer_count);
}Sourcepub async fn check_rate_limit(&self) -> Result<RateLimit>
pub async fn check_rate_limit(&self) -> Result<RateLimit>
Checks the current GitHub API rate limit status.
Useful for monitoring API usage and implementing backoff strategies.
§Returns
Rate limit information including limit, remaining requests, and reset time.
§Example
let service = GitHubService::new()?;
let limits = service.check_rate_limit().await?;
println!("Remaining: {}/{}", limits.remaining, limits.limit);
println!("Resets at: {:?}", limits.reset_datetime());
if limits.is_exceeded() {
println!("Rate limited! Wait {:?}", limits.time_until_reset());
}Sourcepub async fn check_rate_limits(&self) -> Result<RateLimits>
pub async fn check_rate_limits(&self) -> Result<RateLimits>
Returns separate REST core, search and GraphQL quotas when available.
Sourcepub fn has_token(&self) -> bool
pub fn has_token(&self) -> bool
Returns whether a GitHub token is configured.
Useful for conditional logic based on authentication status.
§Example
let service = GitHubService::new()?;
if service.has_token() {
println!("Token configured");
} else {
println!("Anonymous access");
}Sourcepub async fn get_user_starred_repositories(&self) -> Result<Vec<String>>
pub async fn get_user_starred_repositories(&self) -> Result<Vec<String>>
Gets all repositories starred by the authenticated user.
Requires authentication via GITHUB_TOKEN.
§Returns
List of repository full names in “owner/repo” format. Returns a pagination error if more than 100 pages must be fetched.
§Errors
GitHubError::AuthenticationError- No token or invalid tokenGitHubError::RateLimitError- API rate limit exceeded
§Example
let service = GitHubService::new()?;
let starred = service.get_user_starred_repositories().await?;
println!("You have starred {} repositories", starred.len());
for repo in starred.iter().take(5) {
println!(" - {}", repo);
}Sourcepub async fn get_user_profile(&self) -> Result<UserProfile>
pub async fn get_user_profile(&self) -> Result<UserProfile>
Gets the profile of the authenticated user.
Requires authentication via GITHUB_TOKEN.
§Errors
GitHubError::AuthenticationError- No token or invalid token
§Example
let service = GitHubService::new()?;
let profile = service.get_user_profile().await?;
println!("Logged in as: {}", profile.login);
if let Some(name) = profile.name {
println!("Name: {}", name);
}Sourcepub async fn get_repository_stargazers(
&self,
owner: &str,
name: &str,
per_page: Option<u32>,
page: Option<u32>,
) -> Result<Vec<StargazerWithDate>>
pub async fn get_repository_stargazers( &self, owner: &str, name: &str, per_page: Option<u32>, page: Option<u32>, ) -> Result<Vec<StargazerWithDate>>
Gets users who starred a repository with timestamps.
Returns stargazers with the date they starred the repository. Supports pagination. GitHub restricts listing access to repository admins and collaborators; empty results may also reflect access restrictions.
§Arguments
owner- Repository ownername- Repository nameper_page- Results per page (max 100, default 30)page- Page number (default 1)
§Errors
GitHubError::NotFoundError- Repository not foundGitHubError::RateLimitError- API rate limit exceeded
§Example
let service = GitHubService::new()?;
// Get first 100 stargazers
let stargazers = service.get_repository_stargazers(
"rust-lang", "rust",
Some(100), // per_page
Some(1), // page
).await?;
for sg in stargazers {
println!("{} starred at {}", sg.user.login, sg.starred_at);
}Source§impl GitHubService
impl GitHubService
Sourcepub fn with_fetch_options(self, options: FetchOptions) -> Result<Self>
pub fn with_fetch_options(self, options: FetchOptions) -> Result<Self>
Configure limits for account, owned-repository and open-work-item collections.
Sourcepub async fn get_viewer(&self) -> Result<Viewer>
pub async fn get_viewer(&self) -> Result<Viewer>
Fetch the authenticated account and all organizations visible to its token.
Sourcepub async fn get_owned_repositories(
&self,
login: &str,
) -> Result<OwnedRepositories>
pub async fn get_owned_repositories( &self, login: &str, ) -> Result<OwnedRepositories>
List repositories owned by a user or organization, including visible private, forked and archived repositories. Results are sorted by full name.
Sourcepub async fn get_owned_repositories_with_progress<F>(
&self,
login: &str,
progress: F,
) -> Result<OwnedRepositories>
pub async fn get_owned_repositories_with_progress<F>( &self, login: &str, progress: F, ) -> Result<OwnedRepositories>
List owned repositories, lending each validated page to an asynchronous callback.
Use async |page| { ...; Ok(()) } to borrow the page across await points.
Pages are provisional until this method succeeds. A callback error or dropping
the returned future cancels traversal; no background tasks are spawned.
GitHub does not provide a transactional snapshot across pages.
Source§impl GitHubService
impl GitHubService
Sourcepub async fn get_open_issues(
&self,
owner: &str,
name: &str,
) -> Result<Vec<Issue>>
pub async fn get_open_issues( &self, owner: &str, name: &str, ) -> Result<Vec<Issue>>
Fetch every open work item in one repository, sorted by update time descending.
Sourcepub async fn get_open_issues_for_repositories(
&self,
repositories: &[RepositoryCoordinates],
) -> Result<Vec<Issue>>
pub async fn get_open_issues_for_repositories( &self, repositories: &[RepositoryCoordinates], ) -> Result<Vec<Issue>>
Fetch open work items in explicit repository scopes without rediscovering ownership. Archived repositories are included if supplied; applications choose their scopes.
Sourcepub async fn get_open_issues_with_progress<F>(
&self,
repositories: &[RepositoryCoordinates],
progress: F,
) -> Result<Vec<Issue>>
pub async fn get_open_issues_with_progress<F>( &self, repositories: &[RepositoryCoordinates], progress: F, ) -> Result<Vec<Issue>>
Traverse repository scopes with bounded concurrency and lend each page to an async callback.
Empty scopes return immediately without authentication or a callback.
Use async |page| { ...; Ok(()) } to borrow the page across await points.
Pages are provisional until the whole call succeeds. Callback errors and dropping
the future cancel traversal. No tasks are spawned. Labels and assignees must fit
their embedded 100-node pages, otherwise this returns a pagination error.
Totals, cursors and repository identity are checked; GitHub offers no snapshot isolation.
Source§impl GitHubService
impl GitHubService
Sourcepub async fn get_open_pull_requests(
&self,
owner: &str,
name: &str,
) -> Result<Vec<PullRequest>>
pub async fn get_open_pull_requests( &self, owner: &str, name: &str, ) -> Result<Vec<PullRequest>>
Fetch every open work item in one repository, sorted by update time descending.
Sourcepub async fn get_open_pull_requests_for_repositories(
&self,
repositories: &[RepositoryCoordinates],
) -> Result<Vec<PullRequest>>
pub async fn get_open_pull_requests_for_repositories( &self, repositories: &[RepositoryCoordinates], ) -> Result<Vec<PullRequest>>
Fetch open work items in explicit repository scopes without rediscovering ownership. Archived repositories are included if supplied; applications choose their scopes.
Sourcepub async fn get_open_pull_requests_with_progress<F>(
&self,
repositories: &[RepositoryCoordinates],
progress: F,
) -> Result<Vec<PullRequest>>
pub async fn get_open_pull_requests_with_progress<F>( &self, repositories: &[RepositoryCoordinates], progress: F, ) -> Result<Vec<PullRequest>>
Traverse repository scopes with bounded concurrency and lend each page to an async callback.
Empty scopes return immediately without authentication or a callback.
Use async |page| { ...; Ok(()) } to borrow the page across await points.
Pages are provisional until the whole call succeeds. Callback errors and dropping
the future cancel traversal. No tasks are spawned. Labels and assignees must fit
their embedded 100-node pages, otherwise this returns a pagination error.
Totals, cursors and repository identity are checked; GitHub offers no snapshot isolation.