web-requests

name	web-requests
description	Web request framework for HTTP operations. Use when making API calls, HTTP/REST requests, fetching data from server, downloading content via IWebRequestController, parsing responses, building URLs with URLBuilder, signing requests with Web3 auth chains, or configuring retry policies.
user-invocable	false

Web Requests

Sources

• docs/web-requests-framework.md — Custom web request framework
• docs/web3-authentication.md — Web3 authentication, identity, and signing

---

IWebRequestController API

The primary interface for all HTTP operations:

// GET — strongly typed response
var response = await webRequestController.GetAsync(commonArguments, ct, ReportCategory.AUTHENTICATION);

// POST
var response = await webRequestController.PostAsync(commonArguments, body, ct, ReportCategory.MY_CATEGORY);

// GET texture
var response = await webRequestController.GetTextureAsync(commonArguments, ct, ReportCategory.TEXTURES);

CommonArguments

var commonArguments = new CommonArguments(
    url,                    // URLAddress — required
    attemptsCount: 3,       // Default: 3 (1 initial + 2 retries)
    timeout: 0              // Default: 0 (no timeout)
);

Response Parsing

Use GenericDownloadHandlerUtils for response deserialization:

// Overwrite existing object from JSON (avoids allocation)
await response.OverwriteFromJson(existingObject);

// Create new object from JSON
MyDto dto = await response.CreateFromJson<MyDto>();

// Create from Newtonsoft JSON (for complex types)
MyDto dto = await response.CreateFromNewtonsoftJsonAsync<MyDto>();

// Get raw bytes
byte[] data = await response.GetDataCopy();

Code Example — URL Building + Request + Deserialization

From TokenFileAuthenticator.cs:

private async UniTask<IWeb3Identity> LoginAsync(CancellationToken ct)
{
    string token = contentResult.Value;

    // Build URL with URLBuilder
    urlBuilder.Clear();
    urlBuilder.AppendDomain(URLDomain.FromString(authApiUrl))
              .AppendPath(new URLPath($"identities/{token}"));

    var commonArguments = new CommonArguments(urlBuilder.Build());

    // GET request with Newtonsoft JSON deserialization
    IdentityAuthResponseDto json = await webRequestController
        .GetAsync(commonArguments, ct, ReportCategory.AUTHENTICATION)
        .CreateFromNewtonsoftJsonAsync<IdentityAuthResponseDto>();

    // Use response data
    var authChain = AuthChain.Create();
    foreach (AuthLink authLink in json.identity.authChain)
        authChain.Set(authLink);
    // ...
}

Request Signing

For authenticated requests, use WebRequestSignInfo:

// Create sign info with IWeb3Authenticator
var signInfo = new WebRequestSignInfo(signUrl);

// The framework adds x-identity-auth-chain-N headers automatically
var response = await webRequestController.GetAsync(commonArguments, ct, reportCategory, signInfo);

Auth Chain Construction

// Sign a payload
AuthChain authChain = identity.Sign("payload");

// Manually set headers (if not using framework signing)
int i = 0;
foreach (AuthLink link in authChain)
{
    request.SetRequestHeader($"x-identity-auth-chain-{i}", link.ToJson());
    i++;
}

Identity Access

// Get user address
string address = web3IdentityCache.Identity.Address;

// Check if authenticated
if (web3IdentityCache.Identity != null) { /* ... */ }

Retry Policy

Default Behavior

• Only GET requests are idempotent by default
• Signed requests are NOT idempotent (won't retry)
• Default: up to 2 retries with exponential backoff (1s base, 3x multiplier)

Error Code Qualification

Code	Retry?	Reason
400	No	Bad Request
401	No	Unauthorized
403	No	Forbidden
404	No	Not Found
408	Yes	Request Timeout
429	Yes	Too Many Requests
500	Yes	Internal Server Error
502	Yes	Bad Gateway
503	Yes	Service Unavailable
504	Yes	Gateway Timeout
511	No	Network Auth Required

Forcing Retries

// Force retry even for non-idempotent requests
RetryPolicy.Enforce()

JS API

No retries unless Retry-Delay header present on 429/503.

URL Utilities

Use typed URL structures from URLHelpers:

// Domain
var domain = URLDomain.FromString("https://api.example.com");

// Address
var address = URLAddress.FromString("https://api.example.com/v1/users");

// Builder — chain construction
var builder = new URLBuilder();
builder.Clear();
builder.AppendDomain(domain)
       .AppendPath(new URLPath("v1/users"))
       .AppendParameter(new URLParameter("page", "1"));
URLAddress url = builder.Build();

Design Notes

• The framework is designed to be allocation-free — value types throughout
  • Why: HTTP requests happen frequently in hot paths; GC pressure from request objects would cause frame hitches in the Unity game loop.
• WebRequestHeadersInfo uses pooling for header storage
• IWebRequestsAnalyticsContainer tracks ongoing requests for analytics
• Signed requests are not retried by default
  • Why: Auth chains are time-sensitive — replaying a signed request after delay would fail validation, so retrying is wasteful and potentially confusing for error handling.