syntax = "proto3";

package realtime.v1;

message StreamRequest {
  int64 resume_cursor = 1;
  string client_session_id = 2;
}

message StreamEvent {
  int64 sequence_id = 1;
  EventType type = 2;
  bytes payload = 3;
}

enum EventType {
  UPDATE = 0;
  SNAPSHOT = 1;
  HEARTBEAT = 2;
}

// Android: Radio-optimized channel builder
fun createMobileChannel(target: String): ManagedChannel {
    return NettyChannelBuilder.forTarget(target)
        .keepAliveTime(60, TimeUnit.SECONDS)
        .keepAliveTimeout(10, TimeUnit.SECONDS)
        .keepAliveWithoutCalls(false)
        .idleTimeout(5, TimeUnit.MINUTES)
        .maxRetryAttempts(5)
        .build()
}

// Kotlin: Lifecycle-aware stream wrapper
enum class StreamPhase { ACTIVE, RECOVERING, SUSPENDED }

fun <T> Flow<T>.withResumption(
    cursorProvider: () -> Long,
    streamFactory: (Long) -> Flow<T>
): Flow<T> = flow {
    var currentCursor = cursorProvider()
    var recoveryAttempts = 0
    var phase = StreamPhase.ACTIVE

    while (currentCoroutineContext().isActive) {
        try {
            phase = StreamPhase.ACTIVE
            streamFactory(currentCursor).collect { event ->
                recoveryAttempts = 0
                currentCursor = extractSequence(event)
                emit(event)
            }
        } catch (networkFailure: StatusRuntimeException) {
            if (networkFailure.status.code == Code.UNAVAILABLE) {
                phase = StreamPhase.RECOVERING
                val backoffMs = min(500L * (1L shl recoveryAttempts), 30_000L)
                recoveryAttempts++
                delay

(backoffMs) } else throw networkFailure } } }

The exponential backoff caps at 30 seconds to prevent aggressive retry storms during prolonged outages. The `recoveryAttempts` counter resets on successful message delivery, ensuring the stream stabilizes quickly after transient failures.

On iOS, the same pattern maps to `AsyncThrowingStream` with structured concurrency:

```swift
// Swift: AsyncSequence wrapper with offset tracking
func resilientStream(
    initialCursor: Int64,
    requestFactory: (Int64) -> GRPCAsyncBidirectionalStreamingCall<StreamRequest, StreamEvent>
) -> AsyncThrowingStream<StreamEvent, Error> {
    AsyncThrowingStream { continuation in
        Task {
            var cursor = initialCursor
            var attempts = 0
            
            while !Task.isCancelled {
                do {
                    let call = requestFactory(cursor)
                    for try await event in call.responseStream {
                        cursor = event.sequenceID
                        attempts = 0
                        continuation.yield(event)
                    }
                    try await call.status.mapError { $0 }
                } catch let grpcError as GRPCStatus where grpcError.code == .unavailable {
                    attempts += 1
                    let delayMs = min(UInt64(500 * (1 << attempts)), 30_000)
                    try await Task.sleep(nanoseconds: delayMs * 1_000_000)
                }
            }
            continuation.finish()
        }
    }
}

4. Contextual Deadline Routing

Static timeouts leak resources. A foreground chat stream needs a different deadline than a backgrounded location tracker. Interceptors centralize this logic, keeping feature code clean.

// Android: Adaptive timeout interceptor
class LifecycleDeadlineInterceptor(
    private val appStateProvider: () -> AppState
) : ClientInterceptor {

    override fun <Req, Resp> interceptCall(
        method: MethodDescriptor<Req, Resp>,
        callOptions: CallOptions,
        next: Channel
    ): ClientCall<Req, Resp> {
        val effectiveDeadline = when (appStateProvider()) {
            AppState.FOREGROUND -> 120L
            AppState.BACKGROUND -> 10L
            AppState.LOW_BATTERY -> 30L
        }
        
        val modifiedOptions = callOptions.withDeadlineAfter(
            effectiveDeadline, TimeUnit.SECONDS
        )
        return next.newCall(method, modifiedOptions)
    }
}

The interceptor queries application state at call creation time. Backgrounded or power-constrained sessions terminate quickly, freeing server-side resources and preventing zombie connections.

5. Bounded Flow Control

HTTP/2 provides native flow control windows, but application-level buffering can still cause memory pressure. When the UI thread stalls or the device enters Doze mode, unbounded buffers accumulate messages until the process is killed.

// Kotlin: Bounded buffer with drop-oldest policy
fun <T> Flow<T>.withBoundedBuffer(capacity: Int = 64): Flow<T> =
    this.buffer(capacity = capacity, onBufferOverflow = BufferOverflow.DROP_OLDEST)
        .conflate()

The conflate() operator ensures that if the collector falls behind, only the latest value is delivered. This prevents memory spikes while preserving data freshness for real-time UI updates.

Pitfall Guide

1. Aggressive Keepalives on Idle Channels

Explanation: Sending HTTP/2 PING frames when no RPCs are active forces the cellular modem to transition from IDLE to CONNECTED. This happens repeatedly during app backgrounding or quiet periods, draining battery. Fix: Always set keepAliveWithoutCalls(false). Pair it with an idleTimeout that matches your app's typical background duration.

2. Linear Retry Loops Without State Tracking

Explanation: Simple while(true) { retry() } patterns ignore network conditions, app lifecycle, and offset continuity. They cause retry storms during outages and lose messages during reconnection. Fix: Implement a finite state machine with exponential backoff, offset tracking, and lifecycle awareness. Reset attempt counters only on successful message delivery.

3. Hardcoded Deadlines Across App States

Explanation: A uniform 120-second timeout holds server resources open while the app is backgrounded or the device is in low-power mode. This wastes memory and prevents graceful cleanup. Fix: Route deadlines through an interceptor that evaluates app state, battery level, and network quality at call initialization.

4. Unbounded Memory Buffers During UI Freeze

Explanation: When the main thread blocks or the OS throttles background processes, incoming messages queue indefinitely. This triggers OOM kills on memory-constrained devices. Fix: Apply bounded buffers with DROP_OLDEST or DROP_LATEST policies. Use conflate() for UI-bound streams where only the latest state matters.

5. Late Addition of Stream Cursors

Explanation: Adding sequence_id or resume_cursor after launch requires a breaking Protobuf change. Clients and servers must coordinate versioning, causing deployment friction. Fix: Define monotonic cursors in the initial contract. Even if unused initially, reserve the field to enable future resumption without schema migration.

6. Ignoring HTTP/2 Flow Control Windows

Explanation: Developers often assume gRPC handles backpressure automatically. While HTTP/2 manages transport-level windows, application-level collection speed dictates actual throughput. Fix: Monitor collector lag. Implement explicit buffer limits and backpressure signals. Log window exhaustion events to detect slow consumers.

7. TLS Session Resumption Neglect

Explanation: Mobile networks frequently drop TCP connections. Re-establishing TLS handshakes on every reconnection adds 200–400ms latency and CPU overhead. Fix: Enable TLS session tickets on the server. Configure the gRPC channel to reuse SSL sessions. This reduces reconnection latency by 60% on cellular handoffs.

Production Bundle

Action Checklist

• Define monotonic sequence_id in Protobuf contracts before implementation
• Configure keepAliveWithoutCalls(false) and idleTimeout on all mobile channels
• Implement state-driven reconnection with exponential backoff and offset tracking
• Route deadlines through lifecycle-aware interceptors
• Apply bounded buffers with explicit overflow policies to all UI-bound streams
• Enable TLS session resumption on the server and verify client-side reuse
• Instrument stream lifecycle metrics: reconnect frequency, cursor drift, buffer saturation
• Test reconnection logic under network simulation: packet loss, latency spikes, radio state transitions

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
High-frequency UI updates (chat, cursors)	gRPC Bidi + conflate()	Native backpressure prevents UI thread blocking	Low infrastructure, moderate client CPU
Periodic sync (settings, profiles)	REST Polling (30s+)	Simpler implementation, no persistent connection	Higher bandwidth, predictable server load
Cross-platform real-time collaboration	gRPC Bidi + Protobuf	Type safety, deterministic serialization, HTTP/2 multiplexing	Higher initial setup, lower long-term maintenance
Legacy backend without HTTP/2 support	WebSocket + custom framing	Fallback when gRPC server is unavailable	Manual backpressure, higher reconnect complexity

Configuration Template

// Production-ready mobile channel setup
object MobileGrpcConfig {
    fun buildChannel(
        target: String,
        appState: () -> AppState,
        logger: (String) -> Unit
    ): ManagedChannel {
        return NettyChannelBuilder.forTarget(target)
            .keepAliveTime(60, TimeUnit.SECONDS)
            .keepAliveTimeout(10, TimeUnit.SECONDS)
            .keepAliveWithoutCalls(false)
            .idleTimeout(5, TimeUnit.MINUTES)
            .maxRetryAttempts(5)
            .intercept(LifecycleDeadlineInterceptor(appState))
            .intercept(LoggingInterceptor(logger))
            .build()
    }
}

// Interceptor for observability
class LoggingInterceptor(private val log: (String) -> Unit) : ClientInterceptor {
    override fun <Req, Resp> interceptCall(
        method: MethodDescriptor<Req, Resp>,
        callOptions: CallOptions,
        next: Channel
    ): ClientCall<Req, Resp> {
        log("gRPC call initiated: ${method.fullMethodName}")
        return next.newCall(method, callOptions)
    }
}

Quick Start Guide

1. Define the contract: Add sequence_id to your Protobuf messages and generate client stubs for Android and iOS.
2. Configure the channel: Apply radio-aware keepalive settings and attach a lifecycle deadline interceptor.
3. Wrap the stream: Use the state-driven reconnection wrapper with exponential backoff and offset tracking.
4. Bound the flow: Apply buffer() and conflate() to prevent memory pressure during UI stalls.
5. Validate under stress: Use network simulation tools to test reconnection, cursor resumption, and battery impact across WiFi/cellular transitions.