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:
- an attachment upload,
POST/reports/{id}/attachments; - a CSV download,
GET/reports/{id}/download.
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
| Body | Endpoint kind |
|---|---|
| Small JSON (kilobytes) | A typed endpoint (Microservice SDK) |
| A file or an export, within the limits below | A raw endpoint with SupportsStreaming = true |
| A long computation with a small result | A typed endpoint with a longer timeout (Long requests) |
| A file above the limits below | Not 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:
Gateway:Routing:MaxRequestBodySize(default100MB) is the request body limit. A larger body is answered413 Payload Too Largeat once, with or withoutContent-Length;maxBytesin the answer gives the limit. The router gateway host sets Kestrel’s own body limit to the same value.- Over TCP and TLS the request frame must also fit
MaxFrameSize(16 MiB). The frame carries the body Base64-encoded in JSON, about 4/3 of its size, so a body above about 12 MiB is answered413over those transports, whatever the configured limit. Over UDP the frame must fit one datagram (MaxDatagramSize, 8192 bytes), and over RabbitMQ one message (MaxMessageSize, 16 MiB by default: a body of about 12 MiB). Messaging adds no limit of its own. - A refused body is never sent, so the service’s connection keeps serving other requests.
- An HTTP/1.1 client that keeps sending after the
413may see the connection reset instead of the answer, because the gateway does not read the rest of the body.
Responses:
- A response travels in one frame as well: about 12 MiB of body over TCP and TLS, one datagram over UDP, one message of
MaxMessageSizeover RabbitMQ. The service and the gateway each hold the whole response in memory. - A larger response is answered
502at once: problem typeurn:stellaops:router:response-too-large, titleResponse too large, withmaxBytes(the limit) andactualBytes. The connection keeps serving other requests. Keep responses below the limit, as the sample’s row cap does, or page them.
| Limit | Default | Where to change it |
|---|---|---|
| The endpoint’s timeout | TimeoutSeconds (30 seconds) | The attribute, or defaultTimeout in microservice.yaml |
| The gateway’s cap on any timeout | 120 seconds | Gateway:Routing:GlobalTimeoutCap |
| A request body through the gateway | 100MB | Gateway:Routing:MaxRequestBodySize |
| Kestrel’s request body limit in the router gateway host | The same as the request body limit | Follows Gateway:Routing:MaxRequestBodySize |
| The TCP and TLS frame size, for requests and responses | 16 MiB (16777216 bytes): a body of about 12 MiB | Gateway:Transports:<Name>:MaxFrameSize and the transport client’s MaxFrameSize; set both alike |
| The UDP datagram size, for requests and responses | 8192 bytes | Gateway:Transports:Udp:MaxDatagramSize and the client’s MaxDatagramSize |
| The RabbitMQ message size, for requests and responses | 16 MiB (16777216 bytes): a body of about 12 MiB | Gateway: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
- A typed endpoint reads its body as JSON. Use
IRawStellaEndpointfor files. - An oversized response is answered
502Response too large. Cap what the endpoint produces, or page it;maxBytesin the answer gives the limit. - A proxy in front of the gateway can buffer as well. For large uploads and downloads, turn its request and response buffering off on those paths (Running behind a reverse proxy).
- Buffers in the endpoint grow with the body. Copy in fixed chunks, as the sample does; do not call
ReadToEndAsyncon a large body.
