Add initial event feed support

[ecooper]

This PR adds support for change feeds in the JS driver. To do this, we add a new FeedClient that can be initialized via Client.feed(eventSource). FeedClient can then be used as a async generator for each page or event by event via flatten. nextPage is exposed for consumers who don't want to use the generator pattern.

const feed = client.changeFeed(fql`MyCollection.all().eventSource()`)

try {
  for await (const page of feed) {
    for (const event of page.events) {
      // ... handle event
    }
  }
} catch (error) {
  // ... handle fatal error
};

Or via flatten:

const feed = client.changeFeed(fql`MyCollection.all().eventSource()`)

for await (const user of feed.flatten()) {
  // do something with each event
}

Description

Generally, this PR has surfaced the underlying abstractions aren't really equipped to support more Fauna endpoints. There's a refactoring opportunity across clients and the httpclient, but those changes are likely backwards incompatible. So I tried my best to follow the existing conventions in the codebase.

• FeedClient: Exposes change feed pagination via an async iterator via a public nextPage method. It also surfaces flatten to iterate through all events directly.
• FeedClientConfiguration: The required configuration for the iterator. Primarily, optional start_ts and cursor.
• FeedPage: Because there are errors that are embedded in events that are apparently fatal for the page, FeedPage wraps the events wire response in an iterator. If it sees an event type of "error", it throws. I'm not sure that's idiomatic behavior in JS (since you can continue to fetch pages after this event), but I kept parity with the python driver. Additionally, FeedPage provides public attributes to access meta data about the current page, such as the current cursor.
• HTTPClient generics: HTTPClient interfaces have been updated to support generics. This is the first new API using request other than query.
• wire-protocol.ts: Updated with the wire protocol as I understand it.
• package.json: Updated to use the change feed env flag in docker calls. This will need to be removed when the image is updated.

Updates to naming:

The following changes have been added to address the renaming of this feature:

• EventSource: An interface to represent the output of eventSource() and eventsOn(). EventSource replaces all publicly exported uses of StreamToken. StreamToken can be used anywhere EventSource is specified. This seemed the best way to move towards the correct language while keeping this feature backwards compatible.
• eventSource() and eventsOn(): README and docstring uses of toStream() and changesOn() have been replaced with these new methods. Feed tests use these new FQL methods. Existing streaming tests have not been changes at all to prove backwards compatibility.

Motivation and context

To support change feeds beta in the JS driver.

How was the change tested?

Unit, function, and integration tests were added for all new surface areas.

Change types

• • Bug fix (non-breaking change that fixes an issue)
• • New feature (non-breaking change that adds functionality)
• • Breaking change (backwards-incompatible fix or feature)

Checklist:

• • My code follows the code style of this project.
• • My change requires a change to Fauna documentation.
• • My change requires a change to the README, and I have updated it accordingly.

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[jrodewig]

Narrow +1 on the README aside from some nits. Thanks!

[ptpaterson]

This is looking great! I don't have any really major feedback. Closest question to major is how to handle start_ts and cursor input.

[ptpaterson]

Let's goooo

[echo-bravo-yahoo]

marking as request changes to prevent merge - the only feedback i think is worth blocking over is retryable delaying request 0.

that's not an issue, removing the request changes flag.

[findgriffin]

Just some comments on timeouts.

[jrodewig]

Thanks! Looks good overall. Few bigger pieces of feedback:

• We're using "event source" in place of "stream token" now. I left comments for all the refs in the README, but we prolly also want to update this in the implementation.

• Bryan requested that we give Event Feeds top billing so I'd move that section before the Event Streaming one.

[jrodewig]

Narrow +1 on the docs. I left some nit suggestions, but they're not blocking IMO.