From 8284e98b2d2dc532fecf6e68c5ee42cc155d76c6 Mon Sep 17 00:00:00 2001 From: scottf Date: Mon, 26 Jun 2023 22:06:26 -0400 Subject: [PATCH 1/5] [new] ADR-40 Request Many --- adr/ADR-40.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 adr/ADR-40.md diff --git a/adr/ADR-40.md b/adr/ADR-40.md new file mode 100644 index 0000000..9802340 --- /dev/null +++ b/adr/ADR-40.md @@ -0,0 +1,49 @@ +# Request Many + +| Metadata | Value | +|----------|-----------------------| +| Date | 2023-06-26 | +| Author | @aricart, @scottf | +| Status | Partially Implemented | +| Tags | client | + +## Problem Statement +Have the client support receiving multiple replies from a single request, instead of limiting the client to the first reply. + +## Design + +Making the request and handling multiple replies is straightforward. Much like a simplified fetch, the developer +will provide some basic strategy information that tell how many messages to wait for and how long to wait for those messages. + +## Options + +#### Count + +The number of responses to allow. + +* Responses are accepted until the count is reached. +* Must be used in combination with a time as the count may never be reached. + +#### Sentinel + +A sentinel is a message with an empty payload. + +* Must be used in combination with a time as a sentinel may never be sent. + +#### Max Time + +The amount of time to wait for responses. + +* Responses are accepted until the max time is reached. + +#### First Max / Gap Time + +A combination time... + +* The first response must be received by the first max time or the request expires. +* Subsequent messages must be received in the gap time, the time since the last message was received or the request expires. +* Each time a message is received the gap timer is reset. + +### Combinations +* Sentinel can be used with any other option. +* Both time options can be used together. From 2af68cf3d078f8aa1a824f3fbebe84d27bfb6344 Mon Sep 17 00:00:00 2001 From: scottf Date: Mon, 26 Jun 2023 22:10:06 -0400 Subject: [PATCH 2/5] [new] ADR-40 Request Many --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 079b39c..5c5130f 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,7 @@ This repo is used to capture architectural and design decisions as a reference o |[ADR-34](adr/ADR-34.md)|jetstream, client, server|JetStream Consumers Multiple Filters| |[ADR-36](adr/ADR-36.md)|jetstream, client, server|Subject Mapping Transforms in Streams| |[ADR-37](adr/ADR-37.md)|jetstream, client|JetStream Simplification| +|[ADR-40](adr/ADR-40.md)|client| Request Many| ## Jetstream From a2e4c72686926f03bf4dc5c67ebc6b4384e941dc Mon Sep 17 00:00:00 2001 From: scottf Date: Mon, 26 Jun 2023 22:11:11 -0400 Subject: [PATCH 3/5] [new] ADR-40 Request Many --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5c5130f..5f76963 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ This repo is used to capture architectural and design decisions as a reference o |[ADR-34](adr/ADR-34.md)|jetstream, client, server|JetStream Consumers Multiple Filters| |[ADR-36](adr/ADR-36.md)|jetstream, client, server|Subject Mapping Transforms in Streams| |[ADR-37](adr/ADR-37.md)|jetstream, client|JetStream Simplification| -|[ADR-40](adr/ADR-40.md)|client| Request Many| +|[ADR-40](adr/ADR-40.md)|client|Request Many| ## Jetstream From 199b1e3c9d694dbe73b009764059610b0633359d Mon Sep 17 00:00:00 2001 From: scottf Date: Wed, 28 Jun 2023 08:36:05 -0400 Subject: [PATCH 4/5] review comments 1 --- adr/ADR-40.md | 51 +++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 37 insertions(+), 14 deletions(-) diff --git a/adr/ADR-40.md b/adr/ADR-40.md index 9802340..f84a73b 100644 --- a/adr/ADR-40.md +++ b/adr/ADR-40.md @@ -15,8 +15,27 @@ Have the client support receiving multiple replies from a single request, instea Making the request and handling multiple replies is straightforward. Much like a simplified fetch, the developer will provide some basic strategy information that tell how many messages to wait for and how long to wait for those messages. +* The client doesn't assume success or failure - only that it might receive messages. +The various options are there to short circuit the length of the wait. +* The Subsequent Max value allows for waiting for the service with the slowest latency. (scatter gather) +* The message count allows for waiting for some count of messages or a timer (scatter gather) + ## Options +#### Max Wait + +The maximum amount of time to wait for responses. + +* Responses are accepted until the max time is reached. + +#### First Max / Subsequent Max + +A combination time... + +* The first response must be received by the first max time or the request terminates. +* Subsequent messages must be received in the gap time, the time since the last message was received or the request expires. +* Each time a message is received the gap timer is reset. + #### Count The number of responses to allow. @@ -26,24 +45,28 @@ The number of responses to allow. #### Sentinel -A sentinel is a message with an empty payload. +A sentinel is a message with an empty payload. -* Must be used in combination with a time as a sentinel may never be sent. +* The sentinel strategy allows for waiting for chunked data, +for instance a message that represents a large file that is larger than the max payload. +* It's up to the developer to understand the data, not the client's responsibility. + * For ordering for the chunks, maybe use a header. + * If any chunks were missing, re-issue the request indicating the missing chunk ids. +* Must be used in combination with a time as a sentinel may never be sent or missed. -#### Max Time +## Regarding Time -The amount of time to wait for responses. +It's possible that there is a connectivity issue that prevents messages from reaching the requestor so +a request timeout, versus serving the responses being terminated by meeting a time condition. +It would be useful to be able to differentiate between these, but this may not be possible. Do the best you can. -* Responses are accepted until the max time is reached. +## Defaults +Much like simplification, we could provide common defaults across clients around time options. +* The subsequent max seems like a good candidate for this, for instance 100ms? +* The max wait and first max might do well to default to slightly (100ms) longer than the default request or connection timeout. -#### First Max / Gap Time -A combination time... - -* The first response must be received by the first max time or the request expires. -* Subsequent messages must be received in the gap time, the time since the last message was received or the request expires. -* Each time a message is received the gap timer is reset. +## Additional Discussion -### Combinations -* Sentinel can be used with any other option. -* Both time options can be used together. +Is there some level of implementation that should be considered as basic core behavior, such as the most simple multiple reply with a max wait? +Or should the entire implementation be dealt with like an add-on, similar to KV, OS \ No newline at end of file From 8a85c82efde071fb1d448f93edba275d35766dcc Mon Sep 17 00:00:00 2001 From: Tomasz Pietrek Date: Thu, 16 Nov 2023 20:04:15 +0100 Subject: [PATCH 5/5] Improve request many ADR Signed-off-by: Tomasz Pietrek --- adr/ADR-40.md | 63 +++++++++++++++++++++++++++------------------------ 1 file changed, 33 insertions(+), 30 deletions(-) diff --git a/adr/ADR-40.md b/adr/ADR-40.md index f84a73b..b1b8da4 100644 --- a/adr/ADR-40.md +++ b/adr/ADR-40.md @@ -3,7 +3,7 @@ | Metadata | Value | |----------|-----------------------| | Date | 2023-06-26 | -| Author | @aricart, @scottf | +| Author | @aricart, @scottf, @Jarema | | Status | Partially Implemented | | Tags | client | @@ -12,7 +12,7 @@ Have the client support receiving multiple replies from a single request, instea ## Design -Making the request and handling multiple replies is straightforward. Much like a simplified fetch, the developer +Making the request and handling multiple replies is straightforward. Much like a simplified fetch, the developer will provide some basic strategy information that tell how many messages to wait for and how long to wait for those messages. * The client doesn't assume success or failure - only that it might receive messages. @@ -20,53 +20,56 @@ The various options are there to short circuit the length of the wait. * The Subsequent Max value allows for waiting for the service with the slowest latency. (scatter gather) * The message count allows for waiting for some count of messages or a timer (scatter gather) -## Options +## Config -#### Max Wait +#### Timeout -The maximum amount of time to wait for responses. +**Default: same as default for standard request or 1 second** +If client supports global timeout config, it should be reused as a default here. +The maximum amount of time to wait for responses. * Responses are accepted until the max time is reached. -#### First Max / Subsequent Max +#### Muxing +By default, request many does use client request muxer. + +### Strategies -A combination time... +#### None +Only timeout applies -* The first response must be received by the first max time or the request terminates. -* Subsequent messages must be received in the gap time, the time since the last message was received or the request expires. -* Each time a message is received the gap timer is reset. +#### Interval / Max Jitter +**Default: disabled** + +Max interval that can be encountered between messages. +If interval between any messages is larger than set, client will not wait for more messages. #### Count +**Default: No default. Count is required to use this strategy** The number of responses to allow. * Responses are accepted until the count is reached. * Must be used in combination with a time as the count may never be reached. -#### Sentinel - -A sentinel is a message with an empty payload. - -* The sentinel strategy allows for waiting for chunked data, -for instance a message that represents a large file that is larger than the max payload. -* It's up to the developer to understand the data, not the client's responsibility. - * For ordering for the chunks, maybe use a header. - * If any chunks were missing, re-issue the request indicating the missing chunk ids. -* Must be used in combination with a time as a sentinel may never be sent or missed. - ## Regarding Time - -It's possible that there is a connectivity issue that prevents messages from reaching the requestor so +It's possible that there is a connectivity issue that prevents messages from reaching the requestor so a request timeout, versus serving the responses being terminated by meeting a time condition. It would be useful to be able to differentiate between these, but this may not be possible. Do the best you can. -## Defaults -Much like simplification, we could provide common defaults across clients around time options. -* The subsequent max seems like a good candidate for this, for instance 100ms? -* The max wait and first max might do well to default to slightly (100ms) longer than the default request or connection timeout. +## Additional Discussion +Is there some level of implementation that should be considered as basic core behavior, such as the most simple multiple reply with a max wait? +Or should the entire implementation be dealt with like an add-on, similar to KV, OS +## Beyond Scope, for future consideration -## Additional Discussion +#### Sentinel strategy -Is there some level of implementation that should be considered as basic core behavior, such as the most simple multiple reply with a max wait? -Or should the entire implementation be dealt with like an add-on, similar to KV, OS \ No newline at end of file +A sentinel is a message with an empty payload. + +* The sentinel strategy allows for waiting for chunked data, +for instance a message that represents a large file that is larger than the max payload. +* It's up to the developer to understand the data, not the client's responsibility. + * For ordering for the chunks, maybe use a header. + * If any chunks were missing, re-issue the request indicating the missing chunk ids. +* Must be used in combination with a time as a sentinel may never be sent or missed.