1**Design:** New Feature, **Status:** [Proposed](../../../README.md) 2 3# Event Stream Reconnects 4 5Event streaming allows long-running bi-directional communication between 6customers and AWS services over HTTP/2 connections. 7 8Because a single request is intended to be long-running, services 9usually provide a way for a client to "resume" an interrupted session on 10a new TCP connection. In Kinesis's subscribe-to-shard API, each response 11event includes a `continuationSequenceNumber` that can be specified in a 12request message to pick up from where the disconnect occurred. In 13Transcribe's streaming-transcription API, each response includes a 14`sessionId` with similar semantics. 15 16The current implementation requires the service to write a high-level 17library for handling this logic (e.g. Kinesis's consumer library), or 18for each customer to write this logic by hand. 19[This hand-written code](CurrentState.java) is verbose and error prone. 20 21This mini-design outlines API options for the SDK automatically 22reconnecting when a network error occurs. 23 24## [API Option 1: New Method](prototype/Option1.java) 25 26This option adds a new method to each streaming operation that the 27customer can use to enable automatic reconnects. The customer selects to 28work with or without reconnects based on the method that they use. 29 30```Java 31try (TranscribeStreamingAsyncClient client = TranscribeStreamingAsyncClient.create()) { 32 // ... 33 // Current method (behavior is unchanged) 34 client.startStreamTranscription(audioMetadata, 35 audioStream, 36 responseHandler); 37 38 // New method that transparently reconnects on network errors (name to be bikeshed) 39 client.startStreamTranscriptionWithReconnects(audioMetadata, 40 audioStream, 41 responseHandler); 42 // ... 43} 44``` 45 46## [API Option 2: New Client Configuration](prototype/Option2.java) 47 48This option adds a new setting on the client that the customer can use 49to *disable* automatic reconnects. The customer gets automatic 50reconnects by default, and would need to explicitly disable them if they 51do not want them for their use-case. 52 53```Java 54// Current method is updated to transparently reconnect on network errors 55try (TranscribeStreamingAsyncClient client = 56 TranscribeStreamingAsyncClient.create()) { 57 // ... 58 client.startStreamTranscription(audioMetadata, 59 audioStream, 60 responseHandler); 61 // ... 62} 63 64// New client configuration option can be used to configure reconnect behavior 65try (TranscribeStreamingAsyncClient client = 66 TranscribeStreamingAsyncClient.builder() 67 .overrideConfiguration(c -> c.reconnectPolicy(ReconnectPolicy.none())) 68 .build()) { 69 // ... 70 client.startStreamTranscription(audioMetadata, 71 audioStream, 72 responseHandler); 73 // ... 74} 75``` 76 77## Comparison 78 79| | Option 1 | Option 2 | 80| --- | --- | --- | 81| Discoverability | - | + | 82| Configurability | - | + | 83| Backwards Compatibility | + | - |