Tgstation.Server.Client.ApiClient Class Reference

More...

Inheritance diagram for Tgstation.Server.Client.ApiClient:

Collaboration diagram for Tgstation.Server.Client.ApiClient:

Public Member Functions
	ApiClient (HttpClient httpClient, Uri url, ApiHeaders apiHeaders, ApiHeaders? tokenRefreshHeaders, bool authless)
	Initializes a new instance of the ApiClient class.
async ValueTask	DisposeAsync ()
ValueTask< TResult >	Create< TResult > (string route, CancellationToken cancellationToken)
	Run an HTTP PUT request. Template Parameters TResult The type of the response body. Parameters route The server route to make the request to. cancellationToken The CancellationToken for the operation. Returns A ValueTask<TResult> resulting in the response body as a TResult .
ValueTask< TResult >	Read< TResult > (string route, CancellationToken cancellationToken)
	Run an HTTP GET request. Template Parameters TResult The type of the response body. Parameters route The server route to make the request to. cancellationToken The CancellationToken for the operation. Returns A ValueTask<TResult> resulting in the response body as a TResult .
ValueTask< TResult >	Update< TResult > (string route, CancellationToken cancellationToken)
	Run an HTTP POST request. Template Parameters TResult The type of the response body. Parameters route The server route to make the request to. cancellationToken The CancellationToken for the operation. Returns A ValueTask<TResult> resulting in the response body as a TResult .
ValueTask< TResult >	Update< TBody, TResult > (string route, TBody body, CancellationToken cancellationToken)
	Run an HTTP POST request. Template Parameters TBody The type to of the request body. TResult The type of the response body. Parameters route The server route to make the request to. body The request body. cancellationToken The CancellationToken for the operation. Returns A ValueTask<TResult> resulting in the response body as a TResult .
ValueTask	Patch (string route, CancellationToken cancellationToken)
	Run an HTTP PATCH request. Parameters route The server route to make the request to. cancellationToken The CancellationToken for the operation. Returns A ValueTask representing the running operation.
ValueTask	Update< TBody > (string route, TBody body, CancellationToken cancellationToken)
	Run an HTTP POST request. Template Parameters TBody The type to of the request body. Parameters route The server route to make the request to. body The request body. cancellationToken The CancellationToken for the operation. Returns A ValueTask representing the running operation.
ValueTask< TResult >	Create< TBody, TResult > (string route, TBody body, CancellationToken cancellationToken)
	Run an HTTP PUT request. Template Parameters TBody The type to of the request body. TResult The type of the response body. Parameters route The server route to make the request to. body The request body. cancellationToken The CancellationToken for the operation. Returns A ValueTask<TResult> resulting in the response body as a TResult .
ValueTask	Delete (string route, CancellationToken cancellationToken)
	Run an HTTP DELETE request. Parameters route The server route to make the request to. cancellationToken The CancellationToken for the operation. Returns A ValueTask representing the running operation.
ValueTask< TResult >	Create< TBody, TResult > (string route, TBody body, long instanceId, CancellationToken cancellationToken)
	Run an HTTP PUT request. Template Parameters TBody The type to of the request body. TResult The type of the response body. Parameters route The server route to make the request to. body The request body. instanceId The instance EntityId.Id to make the request to. cancellationToken The CancellationToken for the operation. Returns A ValueTask<TResult> resulting in the response body as a TResult .
ValueTask< TResult >	Read< TResult > (string route, long instanceId, CancellationToken cancellationToken)
	Run an HTTP GET request. Template Parameters TResult The type of the response body. Parameters route The server route to make the request to. instanceId The instance EntityId.Id to make the request to. cancellationToken The CancellationToken for the operation. Returns A ValueTask<TResult> resulting in the response body as a TResult .
ValueTask< TResult >	Update< TBody, TResult > (string route, TBody body, long instanceId, CancellationToken cancellationToken)
	Run an HTTP POST request. Template Parameters TBody The type to of the request body. TResult The type of the response body. Parameters route The server route to make the request to. body The request body. instanceId The instance EntityId.Id to make the request to. cancellationToken The CancellationToken for the operation. Returns A ValueTask<TResult> resulting in the response body as a TResult .
ValueTask	Delete (string route, long instanceId, CancellationToken cancellationToken)
	Run an HTTP DELETE request. Parameters route The server route to make the request to. instanceId The instance EntityId.Id to make the request to. cancellationToken The CancellationToken for the operation. Returns A ValueTask representing the running operation.
ValueTask	Delete< TBody > (string route, TBody body, long instanceId, CancellationToken cancellationToken)
	Run an HTTP DELETE request. Template Parameters TBody The type to of the request body. Parameters route The server route to make the request to. body The request body. instanceId The instance EntityId.Id to make the request to. cancellationToken The CancellationToken for the operation. Returns A ValueTask representing the running operation.
ValueTask< TResult >	Delete< TResult > (string route, long instanceId, CancellationToken cancellationToken)
	Run an HTTP DELETE request. Template Parameters TResult The type of the response body. Parameters route The server route to make the request to. instanceId The instance EntityId.Id to make the request to. cancellationToken The CancellationToken for the operation. Returns A ValueTask<TResult> resulting in the response body as a TResult .
ValueTask< TResult >	Delete< TBody, TResult > (string route, TBody body, long instanceId, CancellationToken cancellationToken)
	Run an HTTP DELETE request. Template Parameters TBody The type to of the request body. TResult The type of the response body. Parameters route The server route to make the request to. body The request body. instanceId The instance EntityId.Id to make the request to. cancellationToken The CancellationToken for the operation. Returns A ValueTask representing the running operation.
ValueTask< TResult >	Create< TResult > (string route, long instanceId, CancellationToken cancellationToken)
	Run an HTTP PUT request. Template Parameters TResult The type of the response body. Parameters route The server route to make the request to. instanceId The instance EntityId.Id to make the request to. cancellationToken The CancellationToken for the operation. Returns A ValueTask<TResult> resulting in the response body as a TResult .
ValueTask< TResult >	Patch< TResult > (string route, long instanceId, CancellationToken cancellationToken)
	Run an HTTP PATCH request. Template Parameters TResult The type of the response body. Parameters route The server route to make the request to. instanceId The instance EntityId.Id to make the request to. cancellationToken The CancellationToken for the operation. Returns A ValueTask<TResult> resulting in the response body as a TResult .
void	AddRequestLogger (IRequestLogger requestLogger)
	Adds a requestLogger to the request pipeline. Parameters requestLogger The IRequestLogger to add.
ValueTask< Stream >	Download (FileTicketResponse ticket, CancellationToken cancellationToken)
	Downloads a file Stream for a given ticket . Parameters ticket The FileTicketResponse to download. cancellationToken The CancellationToken for the operation. Returns A ValueTask<TResult> resulting in the downloaded Stream.
async ValueTask	Upload (FileTicketResponse ticket, Stream? uploadStream, CancellationToken cancellationToken)
	Uploads a given uploadStream for a given ticket . Parameters ticket The FileTicketResponse to download. uploadStream The Stream to upload. null represents an empty file. cancellationToken The CancellationToken for the operation. Returns A ValueTask representing the running operation.
async ValueTask< bool >	RefreshToken (CancellationToken cancellationToken)
	Attempt to refresh the stored Bearer token in Headers.
async ValueTask< IAsyncDisposable >	CreateHubConnection< THubImplementation > (THubImplementation hubImplementation, IRetryPolicy? retryPolicy, Action< ILoggingBuilder >? loggingConfigureAction, CancellationToken cancellationToken)
	Subscribe to all job updates available to the IRestServerClient. Template Parameters THubImplementation The Type of the hub being implemented. Parameters hubImplementation The THubImplementation to use for proxying the methods of the hub connection. retryPolicy The optional IRetryPolicy to use for the backing connection. The default retry policy waits for 1, 2, 4, 8, and 16 seconds, then 30s repeatedly. loggingConfigureAction The optional Action<T1> used to configure a ILoggingBuilder. cancellationToken The CancellationToken for the operation. Returns An IAsyncDisposable representing the lifetime of the subscription.

Protected Member Functions
virtual async ValueTask< TResult >	RunRequest< TResult > (string route, HttpContent? content, HttpMethod method, long? instanceId, bool tokenRefresh, CancellationToken cancellationToken)
	Main request method.

Properties
Uri	Url [get]
	The Uri pointing the tgstation-server.
ApiHeaders	Headers [get, set]
	The ApiHeaders the IApiClient uses.
TimeSpan	Timeout [get, set]
	The request timeout.
Properties inherited from Tgstation.Server.Client.IApiClient

Private Member Functions
ValueTask< TResult >	TResult (route, new object(), HttpMethod.Put, null, false, cancellationToken)
ValueTask< TResult >	TResult (route, null, HttpMethod.Get, null, false, cancellationToken)
ValueTask< TResult >	TResult (route, new object(), HttpMethod.Post, null, false, cancellationToken)
ValueTask< TResult >	TResult (route, new object(), HttpMethod.Put, instanceId, false, cancellationToken)
ValueTask< TResult >	TResult (route, new object(), HttpPatch, instanceId, false, cancellationToken)
async ValueTask< HubConnection >	WrapHubInitialConnectAuthRefresh (Func< ValueTask< HubConnection > > connectFunc, CancellationToken cancellationToken)
	Wrap a hub connection attempt via a connectFunc with proper token refreshing.
async ValueTask< TResult >	RunRequest< TBody, TResult > (string route, TBody? body, HttpMethod method, long? instanceId, bool tokenRefresh, CancellationToken cancellationToken)
	Main request method.
async ValueTask	RunResultlessRequest< TBody > (string route, TBody? body, HttpMethod method, long? instanceId, bool tokenRefresh, CancellationToken cancellationToken)
	Main request method.
ValueTask	RunRequest (string route, HttpMethod method, long? instanceId, bool tokenRefresh, CancellationToken cancellationToken)
	Main request method.

Static Private Member Functions
static void	HandleBadResponse (HttpResponseMessage response, string json)
	Handle a bad HTTP response .

Private Attributes
readonly HttpClient	httpClient
	The HttpClient for the ApiClient.
readonly List< IRequestLogger >	requestLoggers
	The IRequestLoggers used by the ApiClient.
readonly List< HubConnection >	hubConnections
	List of HubConnections created by the ApiClient.
readonly? ApiHeaders	tokenRefreshHeaders
	Backing field for Headers.
readonly SemaphoreSlim	semaphoreSlim
	The SemaphoreSlim for TokenResponse refreshes.
readonly bool	authless
	If the authentication header should be stripped from requests.
ApiHeaders	headers
	Backing field for Headers.
bool	disposed
	If the ApiClient is disposed.

Static Private Attributes
static readonly HttpMethod	HttpPatch = new("PATCH")
	PATCH HttpMethod.
static readonly JsonSerializerSettings	SerializerSettings
	The JsonSerializerSettings to use.

Detailed Description

Definition at line 34 of file ApiClient.cs.

Constructor & Destructor Documentation

ApiClient()

Tgstation.Server.Client.ApiClient.ApiClient	(	HttpClient	httpClient,
		Uri	url,
		ApiHeaders	apiHeaders,
		ApiHeaders?	tokenRefreshHeaders,
		bool	authless
	)

Initializes a new instance of the ApiClient class.

Parameters

httpClient	The value of httpClient.
url	The value of Url.
apiHeaders	The value of Headers.
tokenRefreshHeaders	The value of tokenRefreshHeaders.
authless	The value of authless.

Definition at line 168 of file ApiClient.cs.

        {
            this.httpClient = httpClient ?? throw new ArgumentNullException(nameof(httpClient));
            Url = url ?? throw new ArgumentNullException(nameof(url));
            headers = apiHeaders ?? throw new ArgumentNullException(nameof(apiHeaders));
            this.tokenRefreshHeaders = tokenRefreshHeaders;
            this.authless = authless;
 
            requestLoggers = new List<IRequestLogger>();
            hubConnections = new List<HubConnection>();
            semaphoreSlim = new SemaphoreSlim(1);
        }

References Tgstation.Server.Client.ApiClient.authless, Tgstation.Server.Client.ApiClient.headers, Tgstation.Server.Client.ApiClient.httpClient, Tgstation.Server.Client.ApiClient.hubConnections, Tgstation.Server.Client.ApiClient.requestLoggers, Tgstation.Server.Client.ApiClient.semaphoreSlim, Tgstation.Server.Client.ApiClient.tokenRefreshHeaders, and Tgstation.Server.Client.ApiClient.Url.

Member Function Documentation

AddRequestLogger()

void Tgstation.Server.Client.ApiClient.AddRequestLogger

(

IRequestLogger

requestLogger

)

Adds a requestLogger to the request pipeline.

Parameters

requestLogger

The IRequestLogger to add.

Implements Tgstation.Server.Client.IApiClient.

Create< TBody, TResult >() [1/2]

ValueTask< TResult > Tgstation.Server.Client.ApiClient.Create< TBody, TResult >	(	string	route,
		TBody	body,
		CancellationToken	cancellationToken
	)

Run an HTTP PUT request.

Template Parameters

TBody	The type to of the request body.
TResult	The type of the response body.

Parameters

route	The server route to make the request to.
body	The request body.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask<TResult> resulting in the response body as a TResult .

Implements Tgstation.Server.Client.IApiClient.

Type Constraints

TBody	:	class
TBody	:	RunRequest
TBody	:	TBody
TBody	:	TResult
TBody	:	route
TBody	:	body
TBody	:	HttpMethod.Put
TBody	:	null
TBody	:	false
TBody	:	cancellationToken

Create< TBody, TResult >() [2/2]

ValueTask< TResult > Tgstation.Server.Client.ApiClient.Create< TBody, TResult >	(	string	route,
		TBody	body,
		long	instanceId,
		CancellationToken	cancellationToken
	)

Run an HTTP PUT request.

Template Parameters

TBody	The type to of the request body.
TResult	The type of the response body.

Parameters

route	The server route to make the request to.
body	The request body.
instanceId	The instance EntityId.Id to make the request to.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask<TResult> resulting in the response body as a TResult .

Implements Tgstation.Server.Client.IApiClient.

Type Constraints

TBody	:	class
TBody	:	RunRequest
TBody	:	TBody
TBody	:	TResult
TBody	:	route
TBody	:	body
TBody	:	HttpMethod.Put
TBody	:	instanceId
TBody	:	false
TBody	:	cancellationToken

Create< TResult >() [1/2]

ValueTask< TResult > Tgstation.Server.Client.ApiClient.Create< TResult >	(	string	route,
		CancellationToken	cancellationToken
	)

Run an HTTP PUT request.

Template Parameters

TResult

The type of the response body.

Parameters

route	The server route to make the request to.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask<TResult> resulting in the response body as a TResult .

Implements Tgstation.Server.Client.IApiClient.

Create< TResult >() [2/2]

ValueTask< TResult > Tgstation.Server.Client.ApiClient.Create< TResult >	(	string	route,
		long	instanceId,
		CancellationToken	cancellationToken
	)

Run an HTTP PUT request.

Template Parameters

TResult

The type of the response body.

Parameters

route	The server route to make the request to.
instanceId	The instance EntityId.Id to make the request to.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask<TResult> resulting in the response body as a TResult .

Implements Tgstation.Server.Client.IApiClient.

CreateHubConnection< THubImplementation >()

async ValueTask< IAsyncDisposable > Tgstation.Server.Client.ApiClient.CreateHubConnection< THubImplementation >	(	THubImplementation	hubImplementation,
		IRetryPolicy?	retryPolicy,
		Action< ILoggingBuilder >?	loggingConfigureAction,
		CancellationToken	cancellationToken
	)

Subscribe to all job updates available to the IRestServerClient.

Template Parameters

THubImplementation

The Type of the hub being implemented.

Parameters

hubImplementation	The THubImplementation to use for proxying the methods of the hub connection.
retryPolicy	The optional IRetryPolicy to use for the backing connection. The default retry policy waits for 1, 2, 4, 8, and 16 seconds, then 30s repeatedly.
loggingConfigureAction	The optional Action<T1> used to configure a ILoggingBuilder.
cancellationToken	The CancellationToken for the operation.

Returns

An IAsyncDisposable representing the lifetime of the subscription.

Implements Tgstation.Server.Client.IApiClient.

Type Constraints

THubImplementation

:

class

Definition at line 360 of file ApiClient.cs.

                                     : class
        {
            if (hubImplementation == null)
                throw new ArgumentNullException(nameof(hubImplementation));
 
            retryPolicy ??= new InfiniteThirtySecondMaxRetryPolicy();
 
            var wrappedPolicy = new ApiClientTokenRefreshRetryPolicy(this, retryPolicy);
 
            HubConnection? hubConnection = null;
            var hubConnectionBuilder = new HubConnectionBuilder()
                .AddNewtonsoftJsonProtocol(options =>
                {
                    options.PayloadSerializerSettings = SerializerSettings;
                })
                .WithAutomaticReconnect(wrappedPolicy)
                .WithUrl(
                    new Uri(Url, Routes.JobsHub),
                    HttpTransportType.ServerSentEvents,
                    options =>
                    {
                        options.AccessTokenProvider = async () =>
                        {
                            // DCT: None available.
                            if (Headers.Token == null
                                || (Headers.Token.ParseJwt().ValidTo <= DateTime.UtcNow
                                && !await RefreshToken(CancellationToken.None)))
                            {
                                _ = hubConnection!.StopAsync(); // DCT: None available.
                                return null;
                            }
 
                            return Headers.Token.Bearer;
                        };
 
                        options.CloseTimeout = Timeout;
 
                        Headers.SetHubConnectionHeaders(options.Headers);
                    });
 
            if (loggingConfigureAction != null)
                hubConnectionBuilder.ConfigureLogging(loggingConfigureAction);
 
            async ValueTask<HubConnection> AttemptConnect()
            {
                hubConnection = hubConnectionBuilder.Build();
                try
                {
                    hubConnection.Closed += async (error) =>
                    {
                        if (error is HttpRequestException httpRequestException)
                        {
                            // .StatusCode isn't in netstandard but fuck the police
                            var property = error.GetType().GetProperty("StatusCode");
                            if (property != null)
                            {
                                var statusCode = (HttpStatusCode?)property.GetValue(error);
                                if (statusCode == HttpStatusCode.Unauthorized
                                    && !await RefreshToken(CancellationToken.None))
                                    _ = hubConnection!.StopAsync();
                            }
                        }
                    };
 
                    hubConnection.ProxyOn(hubImplementation);
 
                    Task startTask;
                    lock (hubConnections)
                    {
                        if (disposed)
                            throw new ObjectDisposedException(nameof(ApiClient));
 
                        hubConnections.Add(hubConnection);
                        startTask = hubConnection.StartAsync(cancellationToken);
                    }
 
                    await startTask;
 
                    return hubConnection;
                }
                catch
                {
                    bool needsDispose;
                    lock (hubConnections)
                        needsDispose = hubConnections.Remove(hubConnection);
 
                    if (needsDispose)
                        await hubConnection.DisposeAsync();
                    throw;
                }
            }
 
            return await WrapHubInitialConnectAuthRefresh(AttemptConnect, cancellationToken);
        }

References Tgstation.Server.Client.ApiClient.Headers, Tgstation.Server.Api.Routes.JobsHub, Tgstation.Server.Client.ApiClient.SerializerSettings, Tgstation.Server.Api.ApiHeaders.SetHubConnectionHeaders(), Tgstation.Server.Client.ApiClient.Timeout, and Tgstation.Server.Client.ApiClient.Url.

Here is the call graph for this function:

Delete() [1/2]

ValueTask Tgstation.Server.Client.ApiClient.Delete	(	string	route,
		CancellationToken	cancellationToken
	)

Run an HTTP DELETE request.

Parameters

route	The server route to make the request to.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask representing the running operation.

Implements Tgstation.Server.Client.IApiClient.

Delete() [2/2]

ValueTask Tgstation.Server.Client.ApiClient.Delete	(	string	route,
		long	instanceId,
		CancellationToken	cancellationToken
	)

Run an HTTP DELETE request.

Parameters

route	The server route to make the request to.
instanceId	The instance EntityId.Id to make the request to.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask representing the running operation.

Implements Tgstation.Server.Client.IApiClient.

Delete< TBody >()

ValueTask Tgstation.Server.Client.ApiClient.Delete< TBody >	(	string	route,
		TBody	body,
		long	instanceId,
		CancellationToken	cancellationToken
	)

Run an HTTP DELETE request.

Template Parameters

TBody

The type to of the request body.

Parameters

route	The server route to make the request to.
body	The request body.
instanceId	The instance EntityId.Id to make the request to.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask representing the running operation.

Implements Tgstation.Server.Client.IApiClient.

Type Constraints

TBody	:	class
TBody	:	RunResultlessRequest
TBody	:	route
TBody	:	body
TBody	:	HttpMethod.Delete
TBody	:	instanceId
TBody	:	false
TBody	:	cancellationToken

Delete< TBody, TResult >()

ValueTask< TResult > Tgstation.Server.Client.ApiClient.Delete< TBody, TResult >	(	string	route,
		TBody	body,
		long	instanceId,
		CancellationToken	cancellationToken
	)

Run an HTTP DELETE request.

Template Parameters

TBody	The type to of the request body.
TResult	The type of the response body.

Parameters

route	The server route to make the request to.
body	The request body.
instanceId	The instance EntityId.Id to make the request to.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask representing the running operation.

Implements Tgstation.Server.Client.IApiClient.

Type Constraints

TBody	:	class
TBody	:	RunRequest
TBody	:	TBody
TBody	:	TResult
TBody	:	route
TBody	:	body
TBody	:	HttpMethod.Delete
TBody	:	instanceId
TBody	:	false
TBody	:	cancellationToken

Delete< TResult >()

ValueTask< TResult > Tgstation.Server.Client.ApiClient.Delete< TResult >	(	string	route,
		long	instanceId,
		CancellationToken	cancellationToken
	)

Run an HTTP DELETE request.

Template Parameters

TResult

The type of the response body.

Parameters

route	The server route to make the request to.
instanceId	The instance EntityId.Id to make the request to.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask<TResult> resulting in the response body as a TResult .

Implements Tgstation.Server.Client.IApiClient.

DisposeAsync()

async ValueTask Tgstation.Server.Client.ApiClient.DisposeAsync

(

)

Definition at line 187 of file ApiClient.cs.

        {
            List<HubConnection> localHubConnections;
            lock (hubConnections)
            {
                if (disposed)
                    return;
 
                disposed = true;
 
                localHubConnections = [.. hubConnections];
                hubConnections.Clear();
            }
 
            await ValueTaskExtensions.WhenAll(hubConnections.Select(connection => connection.DisposeAsync()));
 
            httpClient.Dispose();
            semaphoreSlim.Dispose();
        }

References Tgstation.Server.Client.ApiClient.disposed, Tgstation.Server.Client.ApiClient.httpClient, Tgstation.Server.Client.ApiClient.hubConnections, Tgstation.Server.Client.ApiClient.semaphoreSlim, and Tgstation.Server.Common.Extensions.ValueTaskExtensions.WhenAll().

Here is the call graph for this function:

Download()

ValueTask< Stream > Tgstation.Server.Client.ApiClient.Download	(	FileTicketResponse	ticket,
		CancellationToken	cancellationToken
	)

Downloads a file Stream for a given ticket .

Parameters

ticket	The FileTicketResponse to download.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask<TResult> resulting in the downloaded Stream.

Implements Tgstation.Server.Client.ITransferClient.

Definition at line 285 of file ApiClient.cs.

        {
            if (ticket == null)
                throw new ArgumentNullException(nameof(ticket));
 
            return RunRequest<Stream>(
                $"{Routes.Transfer}?ticket={HttpUtility.UrlEncode(ticket.FileTicket)}",
                null,
                HttpMethod.Get,
                null,
                false,
                cancellationToken);
        }

Referenced by Tgstation.Server.Client.AdministrationClient.GetLog(), and Tgstation.Server.Client.Components.ConfigurationClient.Read().

Here is the caller graph for this function:

HandleBadResponse()

static void Tgstation.Server.Client.ApiClient.HandleBadResponse ( HttpResponseMessage  response, string  json  )

staticprivate

Handle a bad HTTP response .

Parameters

response	The HttpResponseMessage.
json	The JSON string if any.

Definition at line 116 of file ApiClient.cs.

        {
            ErrorMessageResponse? errorMessage = null;
            try
            {
                // check if json serializes to an error message
                errorMessage = JsonConvert.DeserializeObject<ErrorMessageResponse>(json, SerializerSettings);
            }
            catch (JsonException)
            {
            }
 
#pragma warning disable IDE0010 // Add missing cases
            switch (response.StatusCode)
#pragma warning restore IDE0010 // Add missing cases
            {
                case HttpStatusCode.Unauthorized:
                    throw new UnauthorizedException(errorMessage, response);
                case HttpStatusCode.InternalServerError:
                    throw new ServerErrorException(errorMessage, response);
                case HttpStatusCode.NotImplemented:
                // unprocessable entity
                case (HttpStatusCode)422:
                    throw new MethodNotSupportedException(errorMessage, response);
                case HttpStatusCode.NotFound:
                case HttpStatusCode.Gone:
                case HttpStatusCode.Conflict:
                    throw new ConflictException(errorMessage, response);
                case HttpStatusCode.Forbidden:
                    throw new InsufficientPermissionsException(response);
                case HttpStatusCode.ServiceUnavailable:
                    throw new ServiceUnavailableException(response);
                case HttpStatusCode.RequestTimeout:
                    throw new RequestTimeoutException(response);
                case (HttpStatusCode)429:
                    throw new RateLimitException(errorMessage, response);
                default:
                    if (errorMessage?.ErrorCode == ErrorCode.ApiMismatch)
                        throw new VersionMismatchException(errorMessage, response);
 
                    throw new ApiConflictException(errorMessage, response);
            }
        }

References Tgstation.Server.Client.ApiClient.SerializerSettings.

Patch()

ValueTask Tgstation.Server.Client.ApiClient.Patch	(	string	route,
		CancellationToken	cancellationToken
	)

Run an HTTP PATCH request.

Parameters

route	The server route to make the request to.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask representing the running operation.

Implements Tgstation.Server.Client.IApiClient.

Patch< TResult >()

ValueTask< TResult > Tgstation.Server.Client.ApiClient.Patch< TResult >	(	string	route,
		long	instanceId,
		CancellationToken	cancellationToken
	)

Run an HTTP PATCH request.

Template Parameters

TResult

The type of the response body.

Parameters

route	The server route to make the request to.
instanceId	The instance EntityId.Id to make the request to.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask<TResult> resulting in the response body as a TResult .

Implements Tgstation.Server.Client.IApiClient.

Read< TResult >() [1/2]

ValueTask< TResult > Tgstation.Server.Client.ApiClient.Read< TResult >	(	string	route,
		CancellationToken	cancellationToken
	)

Run an HTTP GET request.

Template Parameters

TResult

The type of the response body.

Parameters

route	The server route to make the request to.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask<TResult> resulting in the response body as a TResult .

Implements Tgstation.Server.Client.IApiClient.

Read< TResult >() [2/2]

ValueTask< TResult > Tgstation.Server.Client.ApiClient.Read< TResult >	(	string	route,
		long	instanceId,
		CancellationToken	cancellationToken
	)

Run an HTTP GET request.

Template Parameters

TResult

The type of the response body.

Parameters

route	The server route to make the request to.
instanceId	The instance EntityId.Id to make the request to.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask<TResult> resulting in the response body as a TResult .

Implements Tgstation.Server.Client.IApiClient.

RefreshToken()

async ValueTask< bool > Tgstation.Server.Client.ApiClient.RefreshToken

(

CancellationToken

cancellationToken

)

Attempt to refresh the stored Bearer token in Headers.

Parameters

cancellationToken

The CancellationToken for the operation.

Returns

A ValueTask<TResult> resulting in true if the refresh was successful, false if a refresh is unable to be performed.

Definition at line 336 of file ApiClient.cs.

        {
            if (tokenRefreshHeaders == null)
                return false;
 
            var startingToken = headers.Token;
            await semaphoreSlim.WaitAsync(cancellationToken).ConfigureAwait(false);
            try
            {
                if (startingToken != headers.Token)
                    return true;
 
                var token = await RunRequest<object, TokenResponse>(Routes.ApiRoot, new object(), HttpMethod.Post, null, true, cancellationToken).ConfigureAwait(false);
                headers = new ApiHeaders(headers.UserAgent!, token);
            }
            finally
            {
                semaphoreSlim.Release();
            }
 
            return true;
        }

References Tgstation.Server.Api.Routes.ApiRoot, Tgstation.Server.Client.ApiClient.headers, Tgstation.Server.Client.ApiClient.semaphoreSlim, Tgstation.Server.Api.ApiHeaders.Token, Tgstation.Server.Client.ApiClient.tokenRefreshHeaders, and Tgstation.Server.Api.ApiHeaders.UserAgent.

Referenced by Tgstation.Server.Client.ApiClientTokenRefreshRetryPolicy.AttemptTokenRefresh().

Here is the caller graph for this function:

RunRequest()

ValueTask Tgstation.Server.Client.ApiClient.RunRequest ( string  route, HttpMethod  method, long?  instanceId, bool  tokenRefresh, CancellationToken  cancellationToken  )

private

Main request method.

Parameters

route	The route to run.
method	The method of the request.
instanceId	The optional instance EntityId.Id for the request.
tokenRefresh	If this is a token refresh operation.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask<TResult> resulting in the response on success.

RunRequest< TBody, TResult >()

async ValueTask< TResult > Tgstation.Server.Client.ApiClient.RunRequest< TBody, TResult > ( string  route, TBody?  body, HttpMethod  method, long?  instanceId, bool  tokenRefresh, CancellationToken  cancellationToken  )

private

Main request method.

Template Parameters

TBody	The body Type.
TResult	The resulting POCO type.

Parameters

route	The route to run.
body	The body of the request.
method	The method of the request.
instanceId	The optional instance EntityId.Id for the request.
tokenRefresh	If this is a token refresh operation.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask<TResult> resulting in the response on success.

Type Constraints

TBody

:

class

Definition at line 620 of file ApiClient.cs.

                        : class
        {
            HttpContent? content = null;
            if (body != null)
                content = new StringContent(
                    JsonConvert.SerializeObject(body, typeof(TBody), Formatting.None, SerializerSettings),
                    Encoding.UTF8,
                    ApiHeaders.ApplicationJsonMime);
 
            using (content)
                return await RunRequest<TResult>(
                    route,
                    content,
                    method,
                    instanceId,
                    tokenRefresh,
                    cancellationToken)
                    .ConfigureAwait(false);
        }

References Tgstation.Server.Api.ApiHeaders.ApplicationJsonMime.

RunRequest< TResult >()

virtual async ValueTask< TResult > Tgstation.Server.Client.ApiClient.RunRequest< TResult > ( string  route, HttpContent?  content, HttpMethod  method, long?  instanceId, bool  tokenRefresh, CancellationToken  cancellationToken  )

protectedvirtual

Main request method.

Template Parameters

TResult

The resulting POCO type.

Parameters

route	The route to run.
content	The HttpContent of the request if any.
method	The method of the request.
instanceId	The optional instance EntityId.Id for the request.
tokenRefresh	If this is a token refresh operation.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask<TResult> resulting in the response on success.

Definition at line 472 of file ApiClient.cs.

        {
            if (route == null)
                throw new ArgumentNullException(nameof(route));
            if (method == null)
                throw new ArgumentNullException(nameof(method));
            if (content == null && (method == HttpMethod.Post || method == HttpMethod.Put))
                throw new InvalidOperationException("content cannot be null for POST or PUT!");
 
            if (disposed)
                throw new ObjectDisposedException(nameof(ApiClient));
 
            HttpResponseMessage response;
            var fullUri = new Uri(Url, route);
            var serializerSettings = SerializerSettings;
            var fileDownload = typeof(TResult) == typeof(Stream);
            using (var request = new HttpRequestMessage(method, fullUri))
            {
                if (content != null)
                    request.Content = content;
 
                try
                {
                    var headersToUse = tokenRefresh ? tokenRefreshHeaders! : headers;
                    headersToUse.SetRequestHeaders(request.Headers, instanceId);
 
                    if (authless)
                        request.Headers.Remove(HeaderNames.Authorization);
                    else
                    {
                        var bearer = headersToUse.Token?.Bearer;
                        if (bearer != null)
                        {
                            var parsed = headersToUse.Token!.ParseJwt();
                            var nbf = parsed.ValidFrom;
                            var now = DateTime.UtcNow;
                            if (nbf >= now)
                            {
                                var delay = (nbf - now).Add(TimeSpan.FromMilliseconds(1));
                                await Task.Delay(delay, cancellationToken);
                            }
                        }
                    }
 
                    if (fileDownload)
                        request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue(MediaTypeNames.Application.Octet));
 
                    await ValueTaskExtensions.WhenAll(requestLoggers.Select(x => x.LogRequest(request, cancellationToken))).ConfigureAwait(false);
 
                    response = await httpClient.SendAsync(request, HttpCompletionOption.ResponseHeadersRead, cancellationToken).ConfigureAwait(false);
                }
                finally
                {
                    // prevent content param from getting disposed
                    request.Content = null;
                }
            }
 
            try
            {
                await ValueTaskExtensions.WhenAll(requestLoggers.Select(x => x.LogResponse(response, cancellationToken))).ConfigureAwait(false);
 
                // just stream
                if (fileDownload && response.IsSuccessStatusCode)
                    return (TResult)(object)await CachedResponseStream.Create(response).ConfigureAwait(false);
            }
            catch
            {
                response.Dispose();
                throw;
            }
 
            using (response)
            {
                var json = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
 
                if (!response.IsSuccessStatusCode)
                {
                    if (!tokenRefresh
                        && response.StatusCode == HttpStatusCode.Unauthorized
                        && await RefreshToken(cancellationToken).ConfigureAwait(false))
                        return await RunRequest<TResult>(route, content, method, instanceId, false, cancellationToken).ConfigureAwait(false);
                    HandleBadResponse(response, json);
                }
 
                if (String.IsNullOrWhiteSpace(json))
                    json = JsonConvert.SerializeObject(new object());
 
                try
                {
                    var result = JsonConvert.DeserializeObject<TResult>(json, serializerSettings);
                    return result!;
                }
                catch (JsonException)
                {
                    throw new UnrecognizedResponseException(response);
                }
            }
        }

References Tgstation.Server.Common.Http.CachedResponseStream.Create(), Tgstation.Server.Api.ApiHeaders.SetRequestHeaders(), and Tgstation.Server.Common.Extensions.ValueTaskExtensions.WhenAll().

Here is the call graph for this function:

RunResultlessRequest< TBody >()

async ValueTask Tgstation.Server.Client.ApiClient.RunResultlessRequest< TBody > ( string  route, TBody?  body, HttpMethod  method, long?  instanceId, bool  tokenRefresh, CancellationToken  cancellationToken  )

private

Main request method.

Template Parameters

TBody

The body Type.

Parameters

route	The route to run.
body	The body of the request.
method	The method of the request.
instanceId	The optional instance EntityId.Id for the request.
tokenRefresh	If this is a token refresh operation.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask<TResult> resulting in the response on success.

Type Constraints

TBody	:	class
TBody	:	await
TBody	:	RunRequest
TBody	:	TBody
TBody	:	object
TBody	:	route
TBody	:	body
TBody	:	method
TBody	:	instanceId
TBody	:	tokenRefresh
TBody	:	cancellationToken

TResult() [1/5]

ValueTask< TResult > Tgstation.Server.Client.ApiClient.TResult ( route  , new   object(), HttpMethod.  Post, null  , false  , cancellationToken    )

private

TResult() [2/5]

ValueTask< TResult > Tgstation.Server.Client.ApiClient.TResult ( route  , new   object(), HttpMethod.  Put, instanceId  , false  , cancellationToken    )

private

TResult() [3/5]

ValueTask< TResult > Tgstation.Server.Client.ApiClient.TResult ( route  , new   object(), HttpMethod.  Put, null  , false  , cancellationToken    )

private

TResult() [4/5]

ValueTask< TResult > Tgstation.Server.Client.ApiClient.TResult ( route  , new   object(), HttpPatch  , instanceId  , false  , cancellationToken    )

private

TResult() [5/5]

ValueTask< TResult > Tgstation.Server.Client.ApiClient.TResult ( route  , null  , HttpMethod.  Get, null  , false  , cancellationToken    )

private

Update< TBody >()

ValueTask Tgstation.Server.Client.ApiClient.Update< TBody >	(	string	route,
		TBody	body,
		CancellationToken	cancellationToken
	)

Run an HTTP POST request.

Template Parameters

TBody

The type to of the request body.

Parameters

route	The server route to make the request to.
body	The request body.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask representing the running operation.

Implements Tgstation.Server.Client.IApiClient.

Type Constraints

TBody	:	class
TBody	:	RunResultlessRequest
TBody	:	route
TBody	:	body
TBody	:	HttpMethod.Post
TBody	:	null
TBody	:	false
TBody	:	cancellationToken

Update< TBody, TResult >() [1/2]

ValueTask< TResult > Tgstation.Server.Client.ApiClient.Update< TBody, TResult >	(	string	route,
		TBody	body,
		CancellationToken	cancellationToken
	)

Run an HTTP POST request.

Template Parameters

TBody	The type to of the request body.
TResult	The type of the response body.

Parameters

route	The server route to make the request to.
body	The request body.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask<TResult> resulting in the response body as a TResult .

Implements Tgstation.Server.Client.IApiClient.

Type Constraints

TBody	:	class
TBody	:	RunRequest
TBody	:	TBody
TBody	:	TResult
TBody	:	route
TBody	:	body
TBody	:	HttpMethod.Post
TBody	:	null
TBody	:	false
TBody	:	cancellationToken

Update< TBody, TResult >() [2/2]

ValueTask< TResult > Tgstation.Server.Client.ApiClient.Update< TBody, TResult >	(	string	route,
		TBody	body,
		long	instanceId,
		CancellationToken	cancellationToken
	)

Run an HTTP POST request.

Template Parameters

TBody	The type to of the request body.
TResult	The type of the response body.

Parameters

route	The server route to make the request to.
body	The request body.
instanceId	The instance EntityId.Id to make the request to.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask<TResult> resulting in the response body as a TResult .

Implements Tgstation.Server.Client.IApiClient.

Type Constraints

TBody	:	class
TBody	:	RunRequest
TBody	:	TBody
TBody	:	TResult
TBody	:	route
TBody	:	body
TBody	:	HttpMethod.Post
TBody	:	instanceId
TBody	:	false
TBody	:	cancellationToken

Update< TResult >()

ValueTask< TResult > Tgstation.Server.Client.ApiClient.Update< TResult >	(	string	route,
		CancellationToken	cancellationToken
	)

Run an HTTP POST request.

Template Parameters

TResult

The type of the response body.

Parameters

route	The server route to make the request to.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask<TResult> resulting in the response body as a TResult .

Implements Tgstation.Server.Client.IApiClient.

Upload()

async ValueTask Tgstation.Server.Client.ApiClient.Upload	(	FileTicketResponse	ticket,
		Stream?	uploadStream,
		CancellationToken	cancellationToken
	)

Uploads a given uploadStream for a given ticket .

Parameters

ticket	The FileTicketResponse to download.
uploadStream	The Stream to upload. null represents an empty file.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask representing the running operation.

Implements Tgstation.Server.Client.ITransferClient.

Definition at line 300 of file ApiClient.cs.

        {
            if (ticket == null)
                throw new ArgumentNullException(nameof(ticket));
 
            MemoryStream? memoryStream = null;
            if (uploadStream == null)
                memoryStream = new MemoryStream();
 
            using (memoryStream)
            {
                var streamContent = new StreamContent(uploadStream ?? memoryStream);
                try
                {
                    await RunRequest<object>(
                        $"{Routes.Transfer}?ticket={HttpUtility.UrlEncode(ticket.FileTicket)}",
                        streamContent,
                        HttpMethod.Put,
                        null,
                        false,
                        cancellationToken)
                        .ConfigureAwait(false);
                    streamContent = null;
                }
                finally
                {
                    streamContent?.Dispose();
                }
            }
        }

Referenced by Tgstation.Server.Client.Components.EngineClient.SetActiveVersion(), Tgstation.Server.Client.AdministrationClient.Update(), and Tgstation.Server.Client.Components.ConfigurationClient.Write().

Here is the caller graph for this function:

WrapHubInitialConnectAuthRefresh()

async ValueTask< HubConnection > Tgstation.Server.Client.ApiClient.WrapHubInitialConnectAuthRefresh ( Func< ValueTask< HubConnection > >  connectFunc, CancellationToken  cancellationToken  )

private

Wrap a hub connection attempt via a connectFunc with proper token refreshing.

Parameters

connectFunc	The HubConnection Func<TResult>.
cancellationToken	The CancellationToken for the operation.

Returns

A ValueTask<TResult> resulting in the connected HubConnection.

Definition at line 585 of file ApiClient.cs.

        {
            try
            {
                return await connectFunc();
            }
            catch (HttpRequestException ex)
            {
                // status code is not in netstandard
                var propertyInfo = ex.GetType().GetProperty("StatusCode");
                if (propertyInfo != null)
                {
                    var statusCode = (HttpStatusCode)propertyInfo.GetValue(ex);
                    if (statusCode != HttpStatusCode.Unauthorized)
                        throw;
                }
 
                await RefreshToken(cancellationToken);
 
                return await connectFunc();
            }
        }

Member Data Documentation

authless

readonly bool Tgstation.Server.Client.ApiClient.authless

private

If the authentication header should be stripped from requests.

Definition at line 99 of file ApiClient.cs.

Referenced by Tgstation.Server.Client.ApiClient.ApiClient().

disposed

bool Tgstation.Server.Client.ApiClient.disposed

private

If the ApiClient is disposed.

Definition at line 109 of file ApiClient.cs.

Referenced by Tgstation.Server.Client.ApiClient.DisposeAsync().

headers

ApiHeaders Tgstation.Server.Client.ApiClient.headers

private

Backing field for Headers.

Definition at line 104 of file ApiClient.cs.

Referenced by Tgstation.Server.Client.ApiClient.ApiClient(), and Tgstation.Server.Client.ApiClient.RefreshToken().

httpClient

readonly HttpClient Tgstation.Server.Client.ApiClient.httpClient

private

The HttpClient for the ApiClient.

Definition at line 74 of file ApiClient.cs.

Referenced by Tgstation.Server.Client.ApiClient.ApiClient(), and Tgstation.Server.Client.ApiClient.DisposeAsync().

HttpPatch

readonly HttpMethod Tgstation.Server.Client.ApiClient.HttpPatch = new("PATCH")

staticprivate

PATCH HttpMethod.

HOW IS THIS NOT INCLUDED IN THE FRAMEWORK??!?!?

Definition at line 40 of file ApiClient.cs.

hubConnections

readonly List<HubConnection> Tgstation.Server.Client.ApiClient.hubConnections

private

List of HubConnections created by the ApiClient.

Definition at line 84 of file ApiClient.cs.

Referenced by Tgstation.Server.Client.ApiClient.ApiClient(), and Tgstation.Server.Client.ApiClient.DisposeAsync().

requestLoggers

readonly List<IRequestLogger> Tgstation.Server.Client.ApiClient.requestLoggers

private

The IRequestLoggers used by the ApiClient.

Definition at line 79 of file ApiClient.cs.

Referenced by Tgstation.Server.Client.ApiClient.ApiClient().

semaphoreSlim

readonly SemaphoreSlim Tgstation.Server.Client.ApiClient.semaphoreSlim

private

The SemaphoreSlim for TokenResponse refreshes.

Definition at line 94 of file ApiClient.cs.

Referenced by Tgstation.Server.Client.ApiClient.ApiClient(), Tgstation.Server.Client.ApiClient.DisposeAsync(), and Tgstation.Server.Client.ApiClient.RefreshToken().

SerializerSettings

readonly JsonSerializerSettings Tgstation.Server.Client.ApiClient.SerializerSettings

staticprivate

Initial value:

= new()
        {
            ContractResolver = new CamelCasePropertyNamesContractResolver(),
            Converters = new[]
            {
                new VersionConverter(),
            },
        }

The JsonSerializerSettings to use.

Definition at line 62 of file ApiClient.cs.

        {
            ContractResolver = new CamelCasePropertyNamesContractResolver(),
            Converters = new[]
            {
                new VersionConverter(),
            },
        };

Referenced by Tgstation.Server.Client.ApiClient.CreateHubConnection< THubImplementation >(), and Tgstation.Server.Client.ApiClient.HandleBadResponse().

tokenRefreshHeaders

readonly? ApiHeaders Tgstation.Server.Client.ApiClient.tokenRefreshHeaders

private

Backing field for Headers.

Definition at line 89 of file ApiClient.cs.

Referenced by Tgstation.Server.Client.ApiClient.ApiClient(), and Tgstation.Server.Client.ApiClient.RefreshToken().

Property Documentation

Headers

ApiHeaders Tgstation.Server.Client.ApiClient.Headers

getset

The ApiHeaders the IApiClient uses.

Implements Tgstation.Server.Client.IApiClient.

Definition at line 46 of file ApiClient.cs.

        {
            get => headers;
            set => headers = value ?? throw new InvalidOperationException("Cannot set null headers!");
        }

Referenced by Tgstation.Server.Client.ApiClient.CreateHubConnection< THubImplementation >().

Timeout

TimeSpan Tgstation.Server.Client.ApiClient.Timeout

getset

The request timeout.

Implements Tgstation.Server.Client.IApiClient.

Definition at line 53 of file ApiClient.cs.

        {
            get => httpClient.Timeout;
            set => httpClient.Timeout = value;
        }

Referenced by Tgstation.Server.Client.ApiClient.CreateHubConnection< THubImplementation >().

Url

Uri Tgstation.Server.Client.ApiClient.Url

get

The Uri pointing the tgstation-server.

Implements Tgstation.Server.Client.IApiClient.

Definition at line 43 of file ApiClient.cs.

{ get; }

Referenced by Tgstation.Server.Client.ApiClient.ApiClient(), and Tgstation.Server.Client.ApiClient.CreateHubConnection< THubImplementation >().

---

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

• src/Tgstation.Server.Client/ApiClient.cs