GitHubShareClient¶
Namespace Nfty.Core.Publish.Community in assembly Nfty.Core.
The GitHub REST calls sharing needs. The token goes only in the Authorization header of requests to the endpoints' API and uploads hosts: never to the published list, never into a message. Every failure leaves as a ShareRules sentence: GitHubAuthException for a refused token, CommunityException for the rest. A caller's own cancellation stays an OperationCanceledException.
Constructors¶
GitHubShareClient(HttpClient, string, CommunityEndpoints, TimeProvider?, TimeSpan?)¶
public GitHubShareClient(HttpClient http, string token, CommunityEndpoints endpoints, TimeProvider? time = null, TimeSpan? bodyTimeout = null);
Parameters
http(HttpClient) - The client every request goes through (not disposed here).token(string) - The person's GitHub access token.endpoints(CommunityEndpoints) - Where the gallery and GitHub live.time(TimeProvider?) - The clock a rate-limit wait is measured against; tests inject one.bodyTimeout(TimeSpan?) - How long a response body may take once its headers arrived (default 30 seconds).
Methods¶
CreateBranchAsync(string, string, string, string, CancellationToken)¶
public Task CreateBranchAsync(string owner, string repo, string branch, string fromSha, CancellationToken ct);
Makes a branch at a commit.
Parameters
owner(string) - The account that owns the repository.repo(string) - The repository name.branch(string) - The new branch name.fromSha(string) - The commit the branch starts at.ct(CancellationToken) - Cancels the request.
CreateReleaseAsync(string, string, string, string, CancellationToken)¶
public Task<GitHubRelease> CreateReleaseAsync(string owner, string repo, string tag, string name, CancellationToken ct);
Makes a published release on a new tag.
Parameters
owner(string) - The account that owns the repository.repo(string) - The repository name.tag(string) - The new tag the release is made on.name(string) - The release title.ct(CancellationToken) - Cancels the request.
Returns. The release GitHub made.
CreateRepoAsync(string, string, CancellationToken)¶
Makes a public repository for the signed-in account, with a first commit so it has a branch.
Parameters
name(string) - The new repository name.description(string) - The repository description.ct(CancellationToken) - Cancels the request.
Returns. The repository GitHub made.
DeleteAssetAsync(string, string, long, CancellationToken)¶
Deletes one file attached to a release.
Parameters
owner(string) - The account that owns the repository.repo(string) - The repository name.assetId(long) - The id of the attached file.ct(CancellationToken) - Cancels the request.
DeleteBranchAsync(string, string, string, CancellationToken)¶
Deletes a branch.
Parameters
owner(string) - The account that owns the repository.repo(string) - The repository name.branch(string) - The branch to delete.ct(CancellationToken) - Cancels the request.
DeleteFileAsync(string, string, string, string, string, string, CancellationToken)¶
public Task DeleteFileAsync(string owner, string repo, string path, string sha, string message, string branch, CancellationToken ct);
Deletes a file at the blob SHA given.
Parameters
owner(string) - The account that owns the repository.repo(string) - The repository name.path(string) - The file path inside the repository.sha(string) - The blob SHA being deleted.message(string) - The commit message.branch(string) - The branch to commit to.ct(CancellationToken) - Cancels the request.
DeleteReleaseAsync(string, string, long, CancellationToken)¶
Deletes a release (its tag stays; see GitHubShareClient.DeleteTagAsync()).
Parameters
owner(string) - The account that owns the repository.repo(string) - The repository name.id(long) - The release id.ct(CancellationToken) - Cancels the request.
DeleteRepoAsync(string, string, CancellationToken)¶
Deletes a repository. Needs the delete_repo scope, which sharing does not ask for, so GitHub usually refuses; the only caller is a rollback that already treats a refusal as best effort.
Parameters
owner(string) - The account that owns the repository.name(string) - The repository name.ct(CancellationToken) - Cancels the request.
DeleteTagAsync(string, string, string, CancellationToken)¶
Deletes a tag.
Parameters
owner(string) - The account that owns the repository.repo(string) - The repository name.tag(string) - The tag to delete.ct(CancellationToken) - Cancels the request.
ForkAsync(string, CancellationToken)¶
Forks the gallery into the signed-in account. GitHub answers with the existing fork when there already is one; a new fork may take a moment to become readable.
Parameters
galleryRepo(string) - The gallery asowner/name.ct(CancellationToken) - Cancels the request.
Returns. The fork, which is the existing one when the account already has it.
GetBranchShaAsync(string, string, string, CancellationToken)¶
public Task<string> GetBranchShaAsync(string owner, string repo, string branch, CancellationToken ct);
The tip commit of a branch.
Parameters
owner(string) - The account that owns the repository.repo(string) - The repository name.branch(string) - The branch to look up.ct(CancellationToken) - Cancels the request.
Returns. The SHA of the branch tip commit.
GetFileAsync(string, string, string, string, CancellationToken)¶
public Task<(byte[], string)?> GetFileAsync(string owner, string repo, string path, string branch, CancellationToken ct);
A file's bytes and blob SHA on a branch, or null when it is not there.
Parameters
owner(string) - The account that owns the repository.repo(string) - The repository name.path(string) - The file path inside the repository.branch(string) - The branch to read from.ct(CancellationToken) - Cancels the request.
Returns. The file bytes and blob SHA, or null when the file is not there.
GetIndexAsync(CancellationToken)¶
The published list, fetched from the gallery's site WITHOUT the token.
Parameters
ct(CancellationToken) - Cancels the request.
Returns. The gallery list as published.
Exceptions
InvalidDataException- The list is damaged.UnsupportedSchemaVersionException- The list is newer or older than this build reads.
GetPullAsync(string, int, CancellationToken)¶
A pull request's state.
Parameters
galleryRepo(string) - The gallery asowner/name.number(int) - The pull request number.ct(CancellationToken) - Cancels the request.
Returns. The state of the pull request and whether it was merged.
GetPullCommentsAsync(string, int, CancellationToken)¶
public Task<IReadOnlyList<string>> GetPullCommentsAsync(string galleryRepo, int number, CancellationToken ct);
The text of a pull request's conversation comments written by the gallery's checks bot (CommunityEndpoints.ActionsBot); anyone else's comment is dropped, since anyone may comment on a pull request.
Parameters
galleryRepo(string) - The gallery asowner/name.number(int) - The pull request number.ct(CancellationToken) - Cancels the request.
Returns. The comment texts written by the checks bot.
GetRepoAsync(string, string, CancellationToken)¶
A repository, or null when it does not exist.
Parameters
owner(string) - The account that owns the repository.name(string) - The repository name.ct(CancellationToken) - Cancels the request.
Returns. The repository, or null when it does not exist.
GetTreeAsync(string, string, string, CancellationToken)¶
public Task<IReadOnlyList<GitHubTreeItem>> GetTreeAsync(string owner, string repo, string branch, CancellationToken ct);
Every item of a branch's tree, recursively.
Parameters
owner(string) - The account that owns the repository.repo(string) - The repository name.branch(string) - The branch whose tree is read.ct(CancellationToken) - Cancels the request.
Returns. Every file and folder item in the tree.
GetViewerAsync(CancellationToken)¶
The signed-in account.
Parameters
ct(CancellationToken) - Cancels the request.
Returns. The account the token signs in.
ListBranchesAsync(string, string, CancellationToken)¶
public Task<IReadOnlyList<string>> ListBranchesAsync(string owner, string repo, CancellationToken ct);
Branch names.
Parameters
owner(string) - The account that owns the repository.repo(string) - The repository name.ct(CancellationToken) - Cancels the request.
Returns. The branch names.
ListOpenPullEntriesAsync(CancellationToken)¶
The entries carried by the gallery's open pull requests (added or changed entries/**/*.json files, read at each request's head commit through the API). Files that don't parse as an entry are skipped.
Parameters
ct(CancellationToken) - Cancels the request.
Returns. The entries the open pull requests carry.
ListReleasesAsync(string, string, CancellationToken)¶
public Task<IReadOnlyList<GitHubRelease>> ListReleasesAsync(string owner, string repo, CancellationToken ct);
The repository's releases with their files.
Parameters
owner(string) - The account that owns the repository.repo(string) - The repository name.ct(CancellationToken) - Cancels the request.
Returns. The releases, each with its attached files.
ListTagsAsync(string, string, CancellationToken)¶
Tag names.
Parameters
owner(string) - The account that owns the repository.repo(string) - The repository name.ct(CancellationToken) - Cancels the request.
Returns. The tag names.
OpenPullAsync(string, string, string, string, CancellationToken)¶
public Task<int> OpenPullAsync(string galleryRepo, string head, string title, string body, CancellationToken ct);
Opens a pull request into the gallery's default branch; head is owner:branch.
Parameters
galleryRepo(string) - The gallery asowner/name.head(string) - The branch to merge, asowner:branch.title(string) - The pull request title.body(string) - The pull request description.ct(CancellationToken) - Cancels the request.
Returns. The number of the pull request opened.
PutFileAsync(string, string, string, byte[], string, string?, string, CancellationToken)¶
public Task PutFileAsync(string owner, string repo, string path, byte[] content, string message, string? sha, string branch, CancellationToken ct);
Creates a file, or replaces it when sha names the version being replaced.
Parameters
owner(string) - The account that owns the repository.repo(string) - The repository name.path(string) - The file path inside the repository.content(byte[]) - The file bytes to write.message(string) - The commit message.sha(string?) - The blob SHA being replaced, or null to create a new file.branch(string) - The branch to commit to.ct(CancellationToken) - Cancels the request.
UploadAssetAsync(GitHubRelease, string, Stream, long, IProgress<long>?, CancellationToken)¶
public Task UploadAssetAsync(GitHubRelease release, string name, Stream content, long length, IProgress<long>? progress, CancellationToken ct);
Attaches a file to a release, streamed: the content is read from content as it is sent, never buffered, with Content-Length stated up front. Progress is the number of bytes sent so far.
Parameters
release(GitHubRelease) - The release to attach the file to.name(string) - The file name the asset is given.content(Stream) - The stream the bytes are read from.length(long) - The exact number of bytes to send.progress(IProgress<long>?) - Receives the bytes sent so far; may be null.ct(CancellationToken) - Cancels the request.