Stream Rate Limiter

Stream Rate Limiter

Stream Rate limiters control the bandwidth (bytes per second) of data transfer for streaming connections. They are essential for creating differentiated service tiers with varying speeds and for ensuring fair resource allocation in streaming scenarios like video, audio, real-time APIs, WebSockets, and Server-Sent Events (SSE).

Types of Stream Rate Limiters

ApiCharge provides two stream rate limiter types to control bandwidth in both directions:

Type	Description	Best For
StreamRateUpload	Controls the upload bandwidth (client to server)	Live streaming, data ingestion, WebSocket client uploads
StreamRateDownload	Controls the download bandwidth (server to client)	Video/audio streaming, data feeds, real-time dashboards

These can be used independently or together to create comprehensive bandwidth management policies.

How Stream Rate Limiters Work

Unlike other rate limiters that simply count and limit overall usage, Stream Rate limiters implement a sophisticated throttling mechanism:

1. Define a maximum bandwidth in bytes per second (BytesPerSecond)
2. Track data transfer in sliding time windows (WindowDurationInSeconds)
3. Dynamically pace data transfer to maintain the specified bandwidth
4. Use a throttling mechanism that introduces controlled delays when necessary

The key differentiator is that Stream Rate limiters don't just cut off access when limits are reached—they actively regulate the flow of data to match the specified bandwidth over time.

Configuration Parameters

Stream Rate limiters have two main configuration parameters:

Parameter	Description	Default
BytesPerSecond	The maximum bandwidth in bytes per second to allow	Required
WindowDurationInSeconds	The time window over which bandwidth is calculated and averaged	60 seconds

Together, these parameters define how ApiCharge will manage the data transfer rate for streaming connections.

Bandwidth Control Experience

Stream Rate limiters provide a superior experience for streaming applications:

• Consistent delivery: Clients experience stable, predictable bandwidth
• Quality control: Service providers can offer different quality tiers
• Uninterrupted service: Streaming continues at the purchased rate
• Client compatibility: Works with standard streaming clients without modifications

This approach is ideal for streaming applications where consistent, uninterrupted delivery is critical for user experience.

Configuration

To configure Stream Rate limiters in your quote definition, use the following syntax:

{
  "ApiChargeQuotes": {
    "Quotes": [
      {
        "RouteId": "video-stream",
        "Duration": 3600,
        "MicroUnitPrice": 500000,
        "RateLimiters": [
          {
            "$type": "StreamRateDownload",
            "BytesPerSecond": 262144,
            "WindowDurationInSeconds": 60
          }
        ]
      }
    ]
  }
}

In this example:

• "$type": "StreamRateDownload": Throttles download speed (server to client)
• "BytesPerSecond": 262144: Limits bandwidth to 256 KB/s
• "WindowDurationInSeconds": 60: Uses a 60-second measurement window

Tiered Streaming Example

Creating multiple quality tiers for a streaming service is a perfect use case for Stream Rate limiters:

{
  "ApiChargeQuotes": {
    "Quotes": [
      {
        "RouteId": "video-service",
        "Duration": 86400,
        "MicroUnitPrice": 500000,
        "RateLimiters": [
          {
            "$type": "StreamRateDownload",
            "BytesPerSecond": 524288,
            "WindowDurationInSeconds": 60
          },
          {
            "$type": "DataLimitDownload",
            "Bytes": 5368709120
          }
        ]
      },
      {
        "RouteId": "video-service",
        "Duration": 86400,
        "MicroUnitPrice": 1000000,
        "RateLimiters": [
          {
            "$type": "StreamRateDownload",
            "BytesPerSecond": 1048576,
            "WindowDurationInSeconds": 60
          },
          {
            "$type": "DataLimitDownload",
            "Bytes": 10737418240
          }
        ]
      },
      {
        "RouteId": "video-service",
        "Duration": 86400,
        "MicroUnitPrice": 2000000,
        "RateLimiters": [
          {
            "$type": "StreamRateDownload",
            "BytesPerSecond": 3145728,
            "WindowDurationInSeconds": 60
          },
          {
            "$type": "DataLimitDownload",
            "Bytes": 21474836480
          }
        ]
      }
    ]
  }
}

This configuration creates three video streaming quality tiers:

• Basic: 512 KB/s (~SD quality) with 5 GB total data
• Standard: 1 MB/s (~HD quality) with 10 GB total data
• Premium: 3 MB/s (~Full HD quality) with 20 GB total data

Note how each tier combines both a Stream Rate limiter (for bandwidth control) and a Data Limit (for total transfer caps), providing comprehensive streaming service management.

Client Experience During Rate Limiting

Stream Rate limiters provide a seamless client experience compared to other rate limiters:

• Connections remain active throughout the streaming session
• Data delivery continues at the purchased bandwidth rate
• Robust handling of clients attempting to exceed purchased bandwidth
• Streaming continuity maintained even at lower rates

This approach is ideal for streaming media, as it prevents interruptions while still enforcing the purchased quality of service.

Deployment Considerations

When using Stream Rate limiters in your deployment, consider these factors:

• Session affinity: In clustered deployments, ensure your load balancer supports sticky sessions for streaming connections
• Connection pooling: Configure appropriately for the expected number of concurrent streaming connections
• Monitoring: Track bandwidth usage and connection counts to optimize tier pricing
• Client behavior: Handle throttled streams gracefully in client applications

Configuring Window Duration

The WindowDurationInSeconds parameter allows you to adjust how the rate limiting behaves:

• Shorter windows (e.g., 10-30 seconds): Best for applications requiring consistent short-term performance
• Longer windows (e.g., 60-300 seconds): Better for applications that benefit from occasional bursts

The recommended default is 60 seconds, which works well for most streaming applications.

Protocol Support

Stream Rate limiters work with all streaming protocols supported by ApiCharge:

• HTTP/1.1 chunked responses: For standard HTTP streaming
• Server-Sent Events (SSE): For one-way server-to-client events
• WebSockets: For bidirectional streaming
• HTTP/2 streams: For multiplexed connections
• gRPC streaming: For streaming RPC calls

The implementation automatically adapts to the protocol in use, providing consistent bandwidth control regardless of the underlying communication mechanism.

Use Cases

Video and Audio Streaming

The most common application is for media streaming services:

• Video platforms with different quality tiers
• Audio streaming services with bitrate-based pricing
• Live event broadcasts with quality options

Real-Time Data Services

For applications that deliver continuous data streams:

• Financial market data feeds
• IoT device telemetry streams
• Real-time analytics dashboards

API Rate Management

For high-volume or continuous API access:

• Weather data streaming APIs
• Traffic or location update services
• Content feeds and syndication endpoints

Advanced Configuration Example

For bi-directional WebSocket applications, you can control bandwidth in both directions:

{
  "RouteId": "websocket-api",
  "Duration": 86400,
  "MicroUnitPrice": 1500000,
  "RateLimiters": [
    {
      "$type": "StreamRateUpload",
      "BytesPerSecond": 262144,
      "WindowDurationInSeconds": 60
    },
    {
      "$type": "StreamRateDownload",
      "BytesPerSecond": 1048576,
      "WindowDurationInSeconds": 60
    },
    {
      "$type": "DataLimitUpload",
      "Bytes": 1073741824
    },
    {
      "$type": "DataLimitDownload",
      "Bytes": 5368709120
    }
  ]
}

This configuration creates an asymmetric WebSocket connection with:

• 256 KB/s upload bandwidth with 1 GB total upload limit
• 1 MB/s download bandwidth with 5 GB total download limit

This is ideal for applications like collaborative editing tools where downloads (content syncing) require more bandwidth than uploads (user edits).

Next Steps

Return to other rate limiter types:

• Call Count - Control the number of API calls
• Data Limits - Control the amount of data transferred