dtoro
d4d99a7473
Problem: the hexagonal refactor churns the backend tree for nine more phases; the UI delivery stack (web/ SPA, cmd/desktop Wails wrapper, compose/web image) must move to its own repo first so doc/layout rewrites land once on a backend-only tree. Change: - New repo git.hubris.network/dtoro/oikos-web (v0.33.0): web/, desktop/ (updateURL repointed to oikos-web releases), compose/, own CI (web + desktop jobs), own deploy script (CI-green gate, TOCTOU guard, version-tagged images, prune-to-3), own webhook receiver on :9798 + launchd unit, own compose project publishing the same 8091:80. - Cutover executed on mac-mini in order: oikos stack's web service stopped+removed, oikos-web project brought up on 8091; outer Caddy untouched (targets the published port) — serving + Authentik flow + /wails 404 quirk verified post-cutover. - Stripped from oikos: web/, cmd/desktop/, compose/web/, desktop CI workflow, ci.yml web job, Makefile ui/desktop/desktop-package/install targets, the compose web service, oikos-web from deploy.sh's fallback prune list; wails + go-keyring dropped from go.mod, vendor synced. - README / CONTRIBUTING / AGENTS.md / .agents dev+operations docs now point at the new repo; mbse + mascot design docs carry a path note. Risk: production SPA serving depends on the new pipeline now; rollback is versioned-image re-up of the old web service from a pre-split checkout (port 8091). Desktop builds installed before the split still check dtoro/oikos releases — one manual reinstall, noted in the oikos-web release notes. Verification: go vet, make test (race), make generate-check, golangci (no new findings; baseline down 400→365); post-cutover curls — localhost:8091 200, /wails/runtime.js 404, outer Caddy 302 Authentik.
142 lines
3.8 KiB
Markdown
142 lines
3.8 KiB
Markdown
# delayed-stream
|
|
|
|
Buffers events from a stream until you are ready to handle them.
|
|
|
|
## Installation
|
|
|
|
``` bash
|
|
npm install delayed-stream
|
|
```
|
|
|
|
## Usage
|
|
|
|
The following example shows how to write a http echo server that delays its
|
|
response by 1000 ms.
|
|
|
|
``` javascript
|
|
var DelayedStream = require('delayed-stream');
|
|
var http = require('http');
|
|
|
|
http.createServer(function(req, res) {
|
|
var delayed = DelayedStream.create(req);
|
|
|
|
setTimeout(function() {
|
|
res.writeHead(200);
|
|
delayed.pipe(res);
|
|
}, 1000);
|
|
});
|
|
```
|
|
|
|
If you are not using `Stream#pipe`, you can also manually release the buffered
|
|
events by calling `delayedStream.resume()`:
|
|
|
|
``` javascript
|
|
var delayed = DelayedStream.create(req);
|
|
|
|
setTimeout(function() {
|
|
// Emit all buffered events and resume underlaying source
|
|
delayed.resume();
|
|
}, 1000);
|
|
```
|
|
|
|
## Implementation
|
|
|
|
In order to use this meta stream properly, here are a few things you should
|
|
know about the implementation.
|
|
|
|
### Event Buffering / Proxying
|
|
|
|
All events of the `source` stream are hijacked by overwriting the `source.emit`
|
|
method. Until node implements a catch-all event listener, this is the only way.
|
|
|
|
However, delayed-stream still continues to emit all events it captures on the
|
|
`source`, regardless of whether you have released the delayed stream yet or
|
|
not.
|
|
|
|
Upon creation, delayed-stream captures all `source` events and stores them in
|
|
an internal event buffer. Once `delayedStream.release()` is called, all
|
|
buffered events are emitted on the `delayedStream`, and the event buffer is
|
|
cleared. After that, delayed-stream merely acts as a proxy for the underlaying
|
|
source.
|
|
|
|
### Error handling
|
|
|
|
Error events on `source` are buffered / proxied just like any other events.
|
|
However, `delayedStream.create` attaches a no-op `'error'` listener to the
|
|
`source`. This way you only have to handle errors on the `delayedStream`
|
|
object, rather than in two places.
|
|
|
|
### Buffer limits
|
|
|
|
delayed-stream provides a `maxDataSize` property that can be used to limit
|
|
the amount of data being buffered. In order to protect you from bad `source`
|
|
streams that don't react to `source.pause()`, this feature is enabled by
|
|
default.
|
|
|
|
## API
|
|
|
|
### DelayedStream.create(source, [options])
|
|
|
|
Returns a new `delayedStream`. Available options are:
|
|
|
|
* `pauseStream`
|
|
* `maxDataSize`
|
|
|
|
The description for those properties can be found below.
|
|
|
|
### delayedStream.source
|
|
|
|
The `source` stream managed by this object. This is useful if you are
|
|
passing your `delayedStream` around, and you still want to access properties
|
|
on the `source` object.
|
|
|
|
### delayedStream.pauseStream = true
|
|
|
|
Whether to pause the underlaying `source` when calling
|
|
`DelayedStream.create()`. Modifying this property afterwards has no effect.
|
|
|
|
### delayedStream.maxDataSize = 1024 * 1024
|
|
|
|
The amount of data to buffer before emitting an `error`.
|
|
|
|
If the underlaying source is emitting `Buffer` objects, the `maxDataSize`
|
|
refers to bytes.
|
|
|
|
If the underlaying source is emitting JavaScript strings, the size refers to
|
|
characters.
|
|
|
|
If you know what you are doing, you can set this property to `Infinity` to
|
|
disable this feature. You can also modify this property during runtime.
|
|
|
|
### delayedStream.dataSize = 0
|
|
|
|
The amount of data buffered so far.
|
|
|
|
### delayedStream.readable
|
|
|
|
An ECMA5 getter that returns the value of `source.readable`.
|
|
|
|
### delayedStream.resume()
|
|
|
|
If the `delayedStream` has not been released so far, `delayedStream.release()`
|
|
is called.
|
|
|
|
In either case, `source.resume()` is called.
|
|
|
|
### delayedStream.pause()
|
|
|
|
Calls `source.pause()`.
|
|
|
|
### delayedStream.pipe(dest)
|
|
|
|
Calls `delayedStream.resume()` and then proxies the arguments to `source.pipe`.
|
|
|
|
### delayedStream.release()
|
|
|
|
Emits and clears all events that have been buffered up so far. This does not
|
|
resume the underlaying source, use `delayedStream.resume()` instead.
|
|
|
|
## License
|
|
|
|
delayed-stream is licensed under the MIT license.
|