Inheritance diagram for Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory:

[legend]

Collaboration diagram for Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory:

[legend]

Public Member Functions

GitHubClientFactory (IAssemblyInformationProvider assemblyInformationProvider, IHttpMessageHandlerFactory httpMessageHandlerFactory, ILogger< GitHubClientFactory > logger, IOptions< GeneralConfiguration > generalConfigurationOptions)

Initializes a new instance of the GitHubClientFactory class.

void Dispose ()

async ValueTask< IGitHubClient > CreateClient (CancellationToken cancellationToken)

Create a IGitHubClient client. Low rate limit unless the server's GitHubAccessToken is set to bypass it.

Parameters

cancellationToken The CancellationToken for the operation.

Returns: A new IGitHubClient.

async ValueTask< IGitHubClient > CreateClient (string accessToken, CancellationToken cancellationToken)

Create a client with authentication using a personal access token.

Parameters

accessToken	The GitHub personal access token.
cancellationToken	The CancellationToken for the operation.

Returns: A new IGitHubClient.

ValueTask< IGitHubClient?> CreateClientForRepository (string accessString, RepositoryIdentifier repositoryIdentifier, CancellationToken cancellationToken)

Creates a GitHub client that will only be used for a given repositoryIdentifier .

Parameters

accessString	The GitHub personal access token or TGS encoded app private key string.
repositoryIdentifier	The RepositoryIdentifier for the GitHub ID that the client will be used to connect to.
cancellationToken	The CancellationToken for the operation.

Returns: A ValueTask<TResult> resulting in a new IGitHubClient for the given repositoryIdentifier or null if authentication failed.

IGitHubClient? CreateAppClient (string tgsEncodedAppPrivateKey)

Create an App (not installation) authenticated IGitHubClient.

Parameters

tgsEncodedAppPrivateKey The TGS encoded app private key string.

Returns: A new app auth IGitHubClient for the given tgsEncodedAppPrivateKey on success null on failure.

Private Member Functions
async ValueTask< IGitHubClient?>	GetOrCreateClient (string? accessString, RepositoryIdentifier? repositoryIdentifier, CancellationToken cancellationToken)
	Retrieve a GitHubClient from the clientCache or add a new one based on a given accessString .

GitHubClient?	CreateAppClientInternal (string tgsEncodedAppPrivateKey)
	Create an App (not installation) authenticated GitHubClient.

GitHubClient	CreateUnauthenticatedClient ()
	Creates an unauthenticated GitHubClient.

Private Attributes
readonly IAssemblyInformationProvider	assemblyInformationProvider
	The IAssemblyInformationProvider for the GitHubClientFactory.

readonly IHttpMessageHandlerFactory	httpMessageHandlerFactory
	The IHttpMessageHandlerFactory for the GitHubClientFactory.

readonly ILogger< GitHubClientFactory >	logger
	The ILogger for the GitHubClientFactory.

readonly GeneralConfiguration	generalConfiguration
	The GeneralConfiguration for the GitHubClientFactory.

readonly Dictionary< string,(GitHubClient Client, DateTimeOffset LastUsed, DateTimeOffset? Expiry)>	clientCache
	Cache of created GitHubClients and last used/expiry times, keyed by access token.

readonly SemaphoreSlim	clientCacheSemaphore
	The SemaphoreSlim used to guard access to clientCache.

Static Private Attributes
const uint	ClientCacheHours = 1
	Limit to the amount of hours a GitHubClient can live in the clientCache.

const uint	AppTokenExpiryGraceMinutes = 15
	Minutes before tokens expire before not using them.

const string	DefaultCacheKey = "~!@TGS_DEFAULT_GITHUB_CLIENT_CACHE_KEY@!~"
	The clientCache KeyValuePair<TKey, TValue>.Key used in place of `null` when accessing a configuration-based client with no token set in GeneralConfiguration.GitHubAccessToken.

Detailed Description

Definition at line 25 of file GitHubClientFactory.cs.

Constructor & Destructor Documentation

◆ GitHubClientFactory()

Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.GitHubClientFactory	(	IAssemblyInformationProvider	assemblyInformationProvider,
		IHttpMessageHandlerFactory	httpMessageHandlerFactory,
		ILogger< GitHubClientFactory >	logger,
		IOptions< GeneralConfiguration >	generalConfigurationOptions
	)

Initializes a new instance of the GitHubClientFactory class.

Parameters

assemblyInformationProvider	The value of assemblyInformationProvider.
httpMessageHandlerFactory	The value of httpMessageHandlerFactory.
logger	The value of logger.
generalConfigurationOptions	The IOptions<TOptions> containing the value of generalConfiguration.

Definition at line 80 of file GitHubClientFactory.cs.

        {
            this.assemblyInformationProvider = assemblyInformationProvider ?? throw new ArgumentNullException(nameof(assemblyInformationProvider));
            this.httpMessageHandlerFactory = httpMessageHandlerFactory ?? throw new ArgumentNullException(nameof(httpMessageHandlerFactory));
            this.logger = logger ?? throw new ArgumentNullException(nameof(logger));
            generalConfiguration = generalConfigurationOptions?.Value ?? throw new ArgumentNullException(nameof(generalConfigurationOptions));
 
            clientCache = new Dictionary<string, (GitHubClient, DateTimeOffset, DateTimeOffset?)>();
            clientCacheSemaphore = new SemaphoreSlim(1, 1);
        }

References Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.assemblyInformationProvider, Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.clientCache, Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.clientCacheSemaphore, Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.generalConfiguration, Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.httpMessageHandlerFactory, and Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.logger.

Member Function Documentation

◆ CreateAppClient()

IGitHubClient? Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.CreateAppClient ( string tgsEncodedAppPrivateKey )

Create an App (not installation) authenticated IGitHubClient.

Parameters

tgsEncodedAppPrivateKey The TGS encoded app private key string.

Returns: A new app auth IGitHubClient for the given tgsEncodedAppPrivateKey on success null on failure.

Implements Tgstation.Server.Host.Utils.GitHub.IGitHubClientFactory.

◆ CreateAppClientInternal()

GitHubClient? Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.CreateAppClientInternal ( string tgsEncodedAppPrivateKey )

private

Create an App (not installation) authenticated GitHubClient.

Parameters

tgsEncodedAppPrivateKey The TGS encoded app private key string.

Returns: A new app auth GitHubClient for the given tgsEncodedAppPrivateKey on success null on failure.

Definition at line 270 of file GitHubClientFactory.cs.

        {
            var client = CreateUnauthenticatedClient();
            var splits = tgsEncodedAppPrivateKey.Split(':');
            if (splits.Length != 2)
            {
                logger.LogError("Failed to parse serialized Client ID & PEM! Expected 2 chunks, got {chunkCount}", splits.Length);
                return null;
            }
 
            byte[] pemBytes;
            try
            {
                pemBytes = Convert.FromBase64String(splits[1]);
            }
            catch (Exception ex)
            {
                logger.LogError(ex, "Failed to parse supposed base64 PEM!");
                return null;
            }
 
            var pem = Encoding.UTF8.GetString(pemBytes);
 
            using var rsa = RSA.Create();
 
            try
            {
                rsa.ImportFromPem(pem);
            }
            catch (Exception ex)
            {
                logger.LogWarning(ex, "Failed to parse PEM!");
                return null;
            }
 
            var signingCredentials = new SigningCredentials(
                 new RsaSecurityKey(rsa),
                 SecurityAlgorithms.RsaSha256)
            {
                // https://stackoverflow.com/questions/62307933/rsa-disposed-object-error-every-other-test
                CryptoProviderFactory = new CryptoProviderFactory
                {
                    CacheSignatureProviders = false,
                },
            };
            var jwtSecurityTokenHandler = new JwtSecurityTokenHandler { SetDefaultTimesOnTokenCreation = false };
 
            var nowDateTime = DateTime.UtcNow;
 
            var appOrClientId = splits[0][RepositorySettings.TgsAppPrivateKeyPrefix.Length..];
 
            var jwt = jwtSecurityTokenHandler.CreateToken(new SecurityTokenDescriptor
            {
                Issuer = appOrClientId,
                Expires = nowDateTime.AddMinutes(10),
                IssuedAt = nowDateTime,
                SigningCredentials = signingCredentials,
            });
 
            var jwtStr = jwtSecurityTokenHandler.WriteToken(jwt);
            client.Credentials = new Credentials(jwtStr, AuthenticationType.Bearer);
            return client;
        }

References Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.CreateUnauthenticatedClient(), Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.logger, and Tgstation.Server.Api.Models.RepositorySettings.TgsAppPrivateKeyPrefix.

Referenced by Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.GetOrCreateClient().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ CreateClient() [1/2]

async ValueTask< IGitHubClient > Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.CreateClient ( CancellationToken cancellationToken )

Create a IGitHubClient client. Low rate limit unless the server's GitHubAccessToken is set to bypass it.

Parameters

cancellationToken The CancellationToken for the operation.

Returns: A new IGitHubClient.

Implements Tgstation.Server.Host.Utils.GitHub.IGitHubClientFactory.

◆ CreateClient() [2/2]

async ValueTask< IGitHubClient > Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.CreateClient	(	string	accessToken,
		CancellationToken	cancellationToken
	)

Create a client with authentication using a personal access token.

Parameters

accessToken	The GitHub personal access token.
cancellationToken	The CancellationToken for the operation.

Returns: A new IGitHubClient.

Implements Tgstation.Server.Host.Utils.GitHub.IGitHubClientFactory.

◆ CreateClientForRepository()

ValueTask< IGitHubClient?> Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.CreateClientForRepository	(	string	accessString,
		RepositoryIdentifier	repositoryIdentifier,
		CancellationToken	cancellationToken
	)

Creates a GitHub client that will only be used for a given repositoryIdentifier .

Parameters

accessString	The GitHub personal access token or TGS encoded app private key string.
repositoryIdentifier	The RepositoryIdentifier for the GitHub ID that the client will be used to connect to.
cancellationToken	The CancellationToken for the operation.

Returns: A ValueTask<TResult> resulting in a new IGitHubClient for the given repositoryIdentifier or null if authentication failed.

Implements Tgstation.Server.Host.Utils.GitHub.IGitHubClientFactory.

◆ CreateUnauthenticatedClient()

GitHubClient Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.CreateUnauthenticatedClient ( )

private

Creates an unauthenticated GitHubClient.

Returns: A new GitHubClient.

Definition at line 338 of file GitHubClientFactory.cs.

        {
            var product = assemblyInformationProvider.ProductInfoHeaderValue.Product!;
#pragma warning disable CA2000 // Dispose objects before losing scope
            var handler = httpMessageHandlerFactory.CreateHandler();
            try
            {
                var clientAdapter = new HttpClientAdapter(() => handler);
#pragma warning restore CA2000 // Dispose objects before losing scope
                handler = null;
                try
                {
                    return new GitHubClient(
                        new Connection(
                            new ProductHeaderValue(
                                product.Name,
                                product.Version),
                            clientAdapter));
                }
                catch
                {
                    clientAdapter.Dispose();
                    throw;
                }
            }
            catch
            {
                handler?.Dispose();
                throw;
            }
        }

References Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.assemblyInformationProvider, Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.httpMessageHandlerFactory, and Tgstation.Server.Host.System.IAssemblyInformationProvider.ProductInfoHeaderValue.

Referenced by Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.CreateAppClientInternal(), and Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.GetOrCreateClient().

Here is the caller graph for this function:

◆ Dispose()

void Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.Dispose ( )

◆ GetOrCreateClient()

async ValueTask< IGitHubClient?> Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.GetOrCreateClient	(	string?	accessString,
		RepositoryIdentifier?	repositoryIdentifier,
		CancellationToken	cancellationToken
	)

private

Retrieve a GitHubClient from the clientCache or add a new one based on a given accessString .

Parameters

accessString	Optional access token to use as credentials or GitHub App private key. If using a TGS encoded app private key, repositoryIdentifier must be set.
repositoryIdentifier	The optional RepositoryIdentifier for the GitHub ID that the client will be used to connect to. Must be set if accessString is a TGS encoded app private key.
cancellationToken	The CancellationToken for the operation.

Returns: A ValueTask<TResult> resulting in the GitHubClient for the given accessString or null if authentication failed.

Definition at line 128 of file GitHubClientFactory.cs.

        {
            GitHubClient? client;
            bool cacheHit;
            DateTimeOffset? lastUsed;
            using (await SemaphoreSlimContext.Lock(clientCacheSemaphore, cancellationToken))
            {
                string cacheKey;
                if (String.IsNullOrWhiteSpace(accessString))
                {
                    accessString = null;
                    cacheKey = DefaultCacheKey;
                }
                else
                    cacheKey = accessString;
 
                var now = DateTimeOffset.UtcNow;
                cacheHit = clientCache.TryGetValue(cacheKey, out var tuple);
                var tokenValid = cacheHit && (!tuple.Expiry.HasValue || tuple.Expiry.Value <= now);
                if (!tokenValid)
                {
                    if (cacheHit)
                    {
                        logger.LogDebug("Previously cached GitHub token has expired!");
                        clientCache.Remove(cacheKey);
                    }
 
                    logger.LogTrace("Creating new GitHubClient...");
 
                    DateTimeOffset? expiry = null;
                    if (accessString != null)
                    {
                        if (accessString.StartsWith(RepositorySettings.TgsAppPrivateKeyPrefix))
                        {
                            if (repositoryIdentifier == null)
                                throw new InvalidOperationException("Cannot create app installation key without target repositoryIdentifier!");
 
                            logger.LogTrace("Performing GitHub App authentication for installation on repository {installationRepositoryId}", repositoryIdentifier);
 
                            client = CreateAppClientInternal(accessString);
                            if (client == null)
                                return null;
 
                            Installation installation;
                            try
                            {
                                var installationTask = repositoryIdentifier.IsSlug
                                    ? client.GitHubApps.GetRepositoryInstallationForCurrent(repositoryIdentifier.Owner, repositoryIdentifier.Name)
                                    : client.GitHubApps.GetRepositoryInstallationForCurrent(repositoryIdentifier.RepositoryId.Value);
                                installation = await installationTask;
                            }
                            catch (Exception ex)
                            {
                                logger.LogError(ex, "Failed to perform app authentication!");
                                return null;
                            }
 
                            cancellationToken.ThrowIfCancellationRequested();
                            try
                            {
                                var installToken = await client.GitHubApps.CreateInstallationToken(installation.Id);
 
                                client.Credentials = new Credentials(installToken.Token);
                                expiry = installToken.ExpiresAt.AddMinutes(-AppTokenExpiryGraceMinutes);
                            }
                            catch (Exception ex)
                            {
                                logger.LogError(ex, "Failed to perform installation authentication!");
                                return null;
                            }
                        }
                        else
                        {
                            client = CreateUnauthenticatedClient();
                            client.Credentials = new Credentials(accessString);
                        }
                    }
                    else
                        client = CreateUnauthenticatedClient();
 
                    clientCache.Add(cacheKey, (Client: client, LastUsed: now, Expiry: expiry));
                    lastUsed = null;
                }
                else
                {
                    logger.LogTrace("Cache hit for GitHubClient");
                    client = tuple.Client;
                    lastUsed = tuple.LastUsed;
                    tuple.LastUsed = now;
                }
 
                // Prune the cache
                var purgeCount = 0U;
                var purgeAfter = now.AddHours(-ClientCacheHours);
                foreach (var key in clientCache.Keys.ToList())
                {
                    if (key == cacheKey)
                        continue; // save the hash lookup
 
                    tuple = clientCache[key];
                    if (tuple.LastUsed <= purgeAfter || (tuple.Expiry.HasValue && tuple.Expiry.Value <= now))
                    {
                        clientCache.Remove(key);
                        ++purgeCount;
                    }
                }
 
                if (purgeCount > 0)
                    logger.LogDebug(
                        "Pruned {count} expired GitHub client(s) from cache that haven't been used in {purgeAfterHours} hours.",
                        purgeCount,
                        ClientCacheHours);
            }
 
            var rateLimitInfo = client.GetLastApiInfo()?.RateLimit;
            if (rateLimitInfo != null)
                if (rateLimitInfo.Remaining == 0)
                    logger.LogWarning(
                        "Requested GitHub client has no requests remaining! Limit resets at {resetTime}",
                        rateLimitInfo.Reset.ToString("o"));
                else if (rateLimitInfo.Remaining < 25) // good luck hitting these lines on codecov
                    logger.LogWarning(
                        "Requested GitHub client has only {remainingRequests} requests remaining after the usage at {lastUse}! Limit resets at {resetTime}",
                        rateLimitInfo.Remaining,
                        lastUsed,
                        rateLimitInfo.Reset.ToString("o"));
                else
                    logger.LogDebug(
                        "Requested GitHub client has {remainingRequests} requests remaining after the usage at {lastUse}. Limit resets at {resetTime}",
                        rateLimitInfo.Remaining,
                        lastUsed,
                        rateLimitInfo.Reset.ToString("o"));
 
            return client;
        }

Here is the call graph for this function:

Member Data Documentation

◆ AppTokenExpiryGraceMinutes

const uint Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.AppTokenExpiryGraceMinutes = 15

staticprivate

Minutes before tokens expire before not using them.

Definition at line 36 of file GitHubClientFactory.cs.

Referenced by Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.GetOrCreateClient().

◆ assemblyInformationProvider

readonly IAssemblyInformationProvider Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.assemblyInformationProvider

private

The IAssemblyInformationProvider for the GitHubClientFactory.

Definition at line 46 of file GitHubClientFactory.cs.

Referenced by Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.CreateUnauthenticatedClient(), and Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.GitHubClientFactory().

◆ clientCache

readonly Dictionary<string, (GitHubClient Client, DateTimeOffset LastUsed, DateTimeOffset? Expiry)> Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.clientCache

private

Cache of created GitHubClients and last used/expiry times, keyed by access token.

Definition at line 66 of file GitHubClientFactory.cs.

Referenced by Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.GetOrCreateClient(), and Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.GitHubClientFactory().

◆ ClientCacheHours

const uint Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.ClientCacheHours = 1

staticprivate

Limit to the amount of hours a GitHubClient can live in the clientCache.

Set to app installation token lifetime, which is the lowest. See https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app.

Definition at line 31 of file GitHubClientFactory.cs.

Referenced by Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.GetOrCreateClient().

◆ clientCacheSemaphore

readonly SemaphoreSlim Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.clientCacheSemaphore

private

The SemaphoreSlim used to guard access to clientCache.

Definition at line 71 of file GitHubClientFactory.cs.

Referenced by Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.GetOrCreateClient(), and Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.GitHubClientFactory().

◆ DefaultCacheKey

const string Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.DefaultCacheKey = "~!@TGS_DEFAULT_GITHUB_CLIENT_CACHE_KEY@!~"

staticprivate

The clientCache KeyValuePair<TKey, TValue>.Key used in place of null when accessing a configuration-based client with no token set in GeneralConfiguration.GitHubAccessToken.

Definition at line 41 of file GitHubClientFactory.cs.

Referenced by Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.GetOrCreateClient().

◆ generalConfiguration

readonly GeneralConfiguration Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.generalConfiguration

private

The GeneralConfiguration for the GitHubClientFactory.

Definition at line 61 of file GitHubClientFactory.cs.

Referenced by Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.GitHubClientFactory().

◆ httpMessageHandlerFactory

readonly IHttpMessageHandlerFactory Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.httpMessageHandlerFactory

private

The IHttpMessageHandlerFactory for the GitHubClientFactory.

Definition at line 51 of file GitHubClientFactory.cs.

Referenced by Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.CreateUnauthenticatedClient(), and Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.GitHubClientFactory().

◆ logger

readonly ILogger<GitHubClientFactory> Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.logger

private

The ILogger for the GitHubClientFactory.

Definition at line 56 of file GitHubClientFactory.cs.

Referenced by Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.CreateAppClientInternal(), Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.GetOrCreateClient(), and Tgstation.Server.Host.Utils.GitHub.GitHubClientFactory.GitHubClientFactory().

The documentation for this class was generated from the following file:

src/Tgstation.Server.Host/Utils/GitHub/GitHubClientFactory.cs

Public Member Functions

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ GitHubClientFactory()

Member Function Documentation

◆ CreateAppClient()

◆ CreateAppClientInternal()

◆ CreateClient() [1/2]

◆ CreateClient() [2/2]

◆ CreateClientForRepository()

◆ CreateUnauthenticatedClient()

◆ Dispose()

◆ GetOrCreateClient()

Member Data Documentation

◆ AppTokenExpiryGraceMinutes

◆ assemblyInformationProvider

◆ clientCache

◆ ClientCacheHours

◆ clientCacheSemaphore

◆ DefaultCacheKey

◆ generalConfiguration

◆ httpMessageHandlerFactory

◆ logger