[whatwg/streams] TransformStream cleanup using "Transformer.cancel" (PR #1283)

This commit adds a `cancel` hook to `Transformer`. This allows users to perform resource cleanup when the readable side of the `TransformStream` is cancelled, or the writable side is aborted.

To preserve existing behavior, when the readable side is cancelled with a reason, the writable side is always immediately aborted with that same reason. The same is true in the reverse case. This means that the status of both sides is always either `closed`, `erroring`, or `erroring` when the `cancel` hook is called.

`flush` and `cancel` are never both called. As per existing behaviour, when the writable side is closed the `flush` hook is called. If the readable side is cancelled while a promise returned from `flush` is still pending, `cancel` is not called. In this scenario the readable side ends up in the "errored" state, while the writable side ends up in the `closed` state.

I have opted for a `cancel` hook instead of a `finally` hook, to mirror the API in `WritableStream` - it has one hook for successful completion (`close`), and one hook for errored completion (`abort`). `Transformer` already has a `flush` hook for successful completion. The logical addition is an `cancel` hook for errored completion.

---

Open questions:

- Is `cancel` the right name? Mirrors `ReadableStream`, but we use `abort` for `WritableStream`.
- Is the immediate cancellation behaviour correct?
  - Ie should call the `cancel` hook before or after cancelling the underlying streams?
  - Calling it before means that current behaviour is changed (number of microticks from `readable.cancel()` to the `writable` actually being aborted).
  - Calling it after means that you can not modify the reason passed to the other side using the `cancel` hook. This is different to `abort` and `cancel` hooks in `WritableStream` and `ReadableStream` respectively.

---

- [ ] At least two implementers are interested (and none opposed):
   * …
   * …
- [ ] [Tests](https://github.com/web-platform-tests/wpt) are written and can be reviewed and commented upon at:
   * …
- [ ] [Implementation bugs](https://github.com/whatwg/meta/blob/main/MAINTAINERS.md#handling-pull-requests) are filed:
   * Chromium: …
   * Gecko: …
   * WebKit: …
   * Deno: …
   * Node.js: …
- [ ] [MDN issue](https://github.com/whatwg/meta/blob/main/MAINTAINERS.md#handling-pull-requests) is filed: …

You can view, comment on, or merge this pull request online at:

  https://github.com/whatwg/streams/pull/1283

-- Commit Summary --

  * TransformStream cleanup using "Transformer.cancel"

-- File Changes --

    M index.bs (101)
    M reference-implementation/lib/Transformer.webidl (2)
    M reference-implementation/lib/abstract-ops/transform-streams.js (53)

-- Patch Links --

https://github.com/whatwg/streams/pull/1283.patch
https://github.com/whatwg/streams/pull/1283.diff

-- 
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/streams/pull/1283
You are receiving this because you are subscribed to this thread.

Message ID: <whatwg/streams/pull/1283@github.com>