Skip to content

Commit

Permalink
Update based on slack discussion.
Browse files Browse the repository at this point in the history
  • Loading branch information
scottf committed Sep 25, 2024
1 parent d4deecd commit 5134e3c
Show file tree
Hide file tree
Showing 3 changed files with 139 additions and 103 deletions.
57 changes: 29 additions & 28 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,34 +7,35 @@ This repository captures Architecture, Design Specifications and Feature Guidanc
# Architecture Decision Records
## Client

|Index|Tags|Description|
|-----|----|-----------|
|[ADR-1](adr/ADR-1.md)|jetstream, client, server|JetStream JSON API Design|
|[ADR-2](adr/ADR-2.md)|jetstream, server, client|NATS Typed Messages|
|[ADR-4](adr/ADR-4.md)|server, client|NATS Message Headers|
|[ADR-5](adr/ADR-5.md)|server, client|Lame Duck Notification|
|[ADR-6](adr/ADR-6.md)|server, client|Naming Rules|
|[ADR-7](adr/ADR-7.md)|server, client, jetstream|NATS Server Error Codes|
|[ADR-8](adr/ADR-8.md)|jetstream, client, kv, spec|JetStream based Key-Value Stores|
|[ADR-9](adr/ADR-9.md)|server, client, jetstream|JetStream Consumer Idle Heartbeats|
|[ADR-10](adr/ADR-10.md)|server, client, jetstream|JetStream Extended Purge|
|[ADR-11](adr/ADR-11.md)|client|Hostname resolution|
|[ADR-13](adr/ADR-13.md)|jetstream, client|Pull Subscribe internals|
|[ADR-14](adr/ADR-14.md)|client, security|JWT library free jwt user generation|
|[ADR-17](adr/ADR-17.md)|jetstream, client|Ordered Consumer|
|[ADR-18](adr/ADR-18.md)|client|URL support for all client options|
|[ADR-19](adr/ADR-19.md)|jetstream, client, kv, objectstore|API prefixes for materialized JetStream views|
|[ADR-20](adr/ADR-20.md)|jetstream, client, objectstore, spec|JetStream based Object Stores|
|[ADR-21](adr/ADR-21.md)|client|NATS Configuration Contexts|
|[ADR-22](adr/ADR-22.md)|jetstream, client|JetStream Publish Retries on No Responders|
|[ADR-31](adr/ADR-31.md)|jetstream, client, server|JetStream Direct Get|
|[ADR-32](adr/ADR-32.md)|client, spec|Service API|
|[ADR-33](adr/ADR-33.md)|jetstream, client, server|Metadata for Stream and Consumer|
|[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, spec|JetStream Simplification|
|[ADR-40](adr/ADR-40.md)|client, server, spec|NATS Connection|
|[ADR-43](adr/ADR-43.md)|jetstream, client, server|JetStream Per-Message TTL|
| Index |Tags|Description|
|-------------------------|----|-----------|
| [ADR-1](adr/ADR-1.md) |jetstream, client, server|JetStream JSON API Design|
| [ADR-2](adr/ADR-2.md) |jetstream, server, client|NATS Typed Messages|
| [ADR-4](adr/ADR-4.md) |server, client|NATS Message Headers|
| [ADR-5](adr/ADR-5.md) |server, client|Lame Duck Notification|
| [ADR-6](adr/ADR-6.md) |server, client|Naming Rules|
| [ADR-7](adr/ADR-7.md) |server, client, jetstream|NATS Server Error Codes|
| [ADR-8](adr/ADR-8.md) |jetstream, client, kv, spec|JetStream based Key-Value Stores|
| [ADR-9](adr/ADR-9.md) |server, client, jetstream|JetStream Consumer Idle Heartbeats|
| [ADR-10](adr/ADR-10.md) |server, client, jetstream|JetStream Extended Purge|
| [ADR-11](adr/ADR-11.md) |client|Hostname resolution|
| [ADR-13](adr/ADR-13.md) |jetstream, client|Pull Subscribe internals|
| [ADR-14](adr/ADR-14.md) |client, security|JWT library free jwt user generation|
| [ADR-17](adr/ADR-17.md) |jetstream, client|Ordered Consumer|
| [ADR-18](adr/ADR-18.md) |client|URL support for all client options|
| [ADR-19](adr/ADR-19.md) |jetstream, client, kv, objectstore|API prefixes for materialized JetStream views|
| [ADR-20](adr/ADR-20.md) |jetstream, client, objectstore, spec|JetStream based Object Stores|
| [ADR-21](adr/ADR-21.md) |client|NATS Configuration Contexts|
| [ADR-22](adr/ADR-22.md) |jetstream, client|JetStream Publish Retries on No Responders|
| [ADR-31](adr/ADR-31.md) |jetstream, client, server|JetStream Direct Get|
| [ADR-32](adr/ADR-32.md) |client, spec|Service API|
| [ADR-33](adr/ADR-33.md) |jetstream, client, server|Metadata for Stream and Consumer|
| [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, spec|JetStream Simplification|
| [ADR-40](adr/ADR-40.md) |client, server, spec|NATS Connection|
| [ADR-43](adr/ADR-43.md) |jetstream, client, server|JetStream Per-Message TTL|
| [ADR-45](adr/ADR-45.md) |client|Request Many|

## Jetstream

Expand Down
110 changes: 110 additions & 0 deletions adr/ADR-45.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
# Request Many

| Metadata | Value |
|----------|----------------------------|
| Date | 2023-06-26 |
| Author | @aricart, @scottf, @Jarema |
| 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.

## Basic Design

The user can provide some configuration controlling how and how long to wait for messages.
The client handles the requests and subscriptions and provides the messages to the user.

* The client doesn't assume success or failure - only that it might receive messages.
* The various configuration options are there to manage and short circuit the length of the wait,
and provide the user the ability to directly stop the processing.
* Request Many is not a recoverable operation, but it could be wrapped in a retry pattern.

## Config

### Total timeout

The maximum amount of time to wait for responses. When the time is expired, the process is complete.
The wait for the first message is always made with the total timeout, since at least one message must come in within the total time.

* Always used
* Defaults to the connection or system request timeout.
* A user could provide a very large value, there has been no discussion of validating. Might be used in a sentinel case or where a user can cancel. Not recommended? Should be discouraged?

### Stall timer

The amount time before to wait for subsequent messages.
Considered "stalled" if this timeout is reached, the request is complete.

* Optional
* Less than 1 or greater than or equal to the total timeout is the same as not supplied.

### Max messages

The maximum number of messages to wait for.
* Optional
* If this number of messages is received, the request is complete.

### Sentinel

While processing the messages, the user should have the ability to indicate that it no longer wants to receive any more messages.
* Optional
* Language specific implementation

## Notes

### Message Handling

Each client must determine how to give messages to the user.
* They could all be collected and given at once.
* They could be put in an iterator, queue, channel, etc.
* A callback could be made.

### End of Data

The developer should notify the user when the request has stopped processing
for completion, sentinel or error conditions but maybe not on if the user cancelled or terminates.
Implementation is language specific based on control flow.

Examples would be sending a marker of some sort to a queue, terminating an iterator, returning a collection, erroring.

### Status Messages / Server Errors

If a status or error comes in place of a user message, this is terminal.
This is probably useful information for the user and can be conveyed as part of the end of data.

#### Callback timing

If callbacks are made in a blocking fashion, the client must account for the time it takes for the user to process the message.

### Sentinel

If the client supports a sentinel, for instance with a callback predicate that accepts the message and returns a boolean,
a return of true would mean continue to process and false would mean stop processing.

### Cancelling

Wherever possible, the user should be able to cancel the request. This is not the sentinel.

## Disconnection

It's possible that there is a connectivity issue that prevents messages from reaching the requestor,
so it might be difficult to differentiate from a total or stall timeout.
If possible and useful in the client, this can be conveyed as part of the end of data.

## Strategies
It's acceptable to make "strategies" via enum / api / helpers / builders / whatever.
Strategies are just pre-canned configurations.

**Strategies are not specified yet, this is just an example**

Here is an example from Javascript. Jitter was the original term for stall.

```js
export enum RequestStrategy {
Timer = "timer",
Count = "count",
JitterTimer = "jitterTimer",
SentinelMsg = "sentinelMsg",
}
```
75 changes: 0 additions & 75 deletions adr/ADR-RM.md

This file was deleted.

0 comments on commit 5134e3c

Please sign in to comment.