Scenario: file uploads and downloads

A raw endpoint takes a request body that is not JSON, such as a file, and returns any body, such as a CSV export. This page shows both directions and the size limits that apply to them.

In this release the Router holds every request and response body in memory and sends it in one frame, also for an endpoint marked with SupportsStreaming = true: the gateway receives the whole request body before it sends the request, and the service produces the whole response before the gateway writes it to the caller. Size uploads and downloads with the limits below.

The worked example is the reports sample service:

Before each release, an automated run uploads 64 KiB and downloads a 2.1 MB file of 200,001 lines through the gateway.

When to use it

BodyEndpoint kind
Small JSON (kilobytes)A typed endpoint (Microservice SDK)
A file or an export, within the limits belowA raw endpoint with SupportsStreaming = true
A long computation with a small resultA typed endpoint with a longer timeout (Long requests)
A file above the limits belowNot through the Router: store the file elsewhere and pass its location

Upload

Declare the endpoint as raw, and give it a timeout that covers the slowest upload:

[StellaEndpoint("POST", "/reports/{id}/attachments", SupportsStreaming = true, TimeoutSeconds = 60)]
public sealed class UploadAttachmentEndpoint : IRawStellaEndpoint

Read context.Body in fixed chunks and write each chunk to storage:

var contentType = context.Headers["Content-Type"] ?? "application/octet-stream";
_logger.LogInformation(
    "Uploading attachment for report {ReportId}, Content-Type: {ContentType}",
    reportId,
    contentType);

// Copy the body in fixed chunks; the gateway has already received all of it.
long totalBytes = 0;
var buffer = new byte[8192];
int bytesRead;

while ((bytesRead = await context.Body.ReadAsync(buffer, cancellationToken)) > 0)
{
    totalBytes += bytesRead;
    // In a real implementation, you would write to storage here
}

_logger.LogInformation(
    "Received {TotalBytes} bytes for report {ReportId}",
    totalBytes,
    reportId);

var response = new
{
    reportId,
    attachmentId = $"ATT-{Guid.NewGuid():N}"[..16].ToUpperInvariant(),
    size = totalBytes,
    uploadedAt = DateTime.UtcNow
};

var headers = new HeaderCollection();
headers.Set("Content-Type", "application/json");
return new RawResponse
{
    StatusCode = 200,
    Headers = headers,
    Body = new MemoryStream(JsonSerializer.SerializeToUtf8Bytes(response))
};

The sample also limits uploads per report with the C# rate limiter (Rate limiting).

Call it:

curl -i -X POST http://localhost:5080/reports/RPT-1/attachments \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/pdf" \
  --data-binary @statement.pdf

Expected result: 200 and a JSON body with the attachment id and its size in bytes.

Download

Return a RawResponse whose Body holds the file. The SDK reads the body to its end and sends it to the gateway in one frame, so cap what the endpoint produces below the frame limit, as the sample does:

/// <summary>
/// A CSV download. The Router holds a whole response in memory and sends it in one frame, so the
/// endpoint caps the file: at most 500,000 rows, about 5.3 MB, below the 16 MiB frame of the TCP and
/// TLS transports. The query parameter rows sets the number of rows.
/// </summary>
[StellaEndpoint("GET", "/reports/{id}/download", SupportsStreaming = true, TimeoutSeconds = 60)]
public sealed class DownloadReportEndpoint : IRawStellaEndpoint
{
    private const int MaxRows = 500_000;

    public Task<RawResponse> HandleAsync(RawRequestContext context, CancellationToken cancellationToken)
    {
        var reportId = context.PathParameters["id"];
        var rows = context.QueryParameters.TryGetValue("rows", out var value)
            && int.TryParse(value, NumberStyles.None, CultureInfo.InvariantCulture, out var parsed)
            ? Math.Clamp(parsed, 1, MaxRows)
            : 10_000;

        var csv = new StringBuilder("row,value\n");
        for (var row = 1; row <= rows; row++)
        {
            cancellationToken.ThrowIfCancellationRequested();
            csv.Append(CultureInfo.InvariantCulture, $"{row},{row * 7 % 1000}\n");
        }

        var headers = new HeaderCollection();
        headers.Set("Content-Type", "text/csv; charset=utf-8");
        headers.Set("Content-Disposition", "attachment; filename=" + reportId + ".csv");
        return Task.FromResult(new RawResponse
        {
            StatusCode = 200,
            Headers = headers,
            Body = new MemoryStream(Encoding.UTF8.GetBytes(csv.ToString()))
        });
    }
}

Call it:

curl -o RPT-1.csv "http://localhost:5080/reports/RPT-1/download?rows=200000" \
  -H "Authorization: Bearer $TOKEN"

Expected result: 200 with Content-Type: text/csv and a file of 200,001 lines. For an endpoint marked with SupportsStreaming, the gateway writes the response without Content-Length, so an HTTP/1.1 caller receives it with Transfer-Encoding: chunked; the gateway still holds the whole body before it writes it.

Limits that apply

Requests:

Responses:

LimitDefaultWhere to change it
The endpoint’s timeoutTimeoutSeconds (30 seconds)The attribute, or defaultTimeout in microservice.yaml
The gateway’s cap on any timeout120 secondsGateway:Routing:GlobalTimeoutCap
A request body through the gateway100MBGateway:Routing:MaxRequestBodySize
Kestrel’s request body limit in the router gateway hostThe same as the request body limitFollows Gateway:Routing:MaxRequestBodySize
The TCP and TLS frame size, for requests and responses16 MiB (16777216 bytes): a body of about 12 MiBGateway:Transports:<Name>:MaxFrameSize and the transport client’s MaxFrameSize; set both alike
The UDP datagram size, for requests and responses8192 bytesGateway:Transports:Udp:MaxDatagramSize and the client’s MaxDatagramSize
The RabbitMQ message size, for requests and responses16 MiB (16777216 bytes): a body of about 12 MiBGateway:Transports:RabbitMq:MaxMessageSize and the client’s MaxMessageSize; at most the broker’s max_message_size

A larger frame size raises both limits, and the memory each request in flight can take in the gateway and the service.

Pitfalls