@velmlabs/unstuck-core 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -86,16 +86,33 @@ interface FrameSink {
86
86
  send(b: Uint8Array): void;
87
87
  readonly bufferedAmount: number;
88
88
  }
89
- /**
90
- * Newest-frame-only sender: never queues more than one pending frame per viewer.
91
- * Slow viewers skip frames instead of building a backlog.
92
- */
93
- declare function createLatestSender(conn: FrameSink, opts?: {
89
+ interface LatestSenderOptions {
94
90
  highWaterMark?: number;
95
- }): {
91
+ /** Clock for the ack timeout (default Date.now). */
92
+ now?: () => number;
93
+ }
94
+ interface LatestSender {
95
+ /** Sends `frame` (an encoded type-1 frame) now if there is room, else keeps it as the one pending frame. */
96
96
  push(frame: Uint8Array): void;
97
+ /** Sends the pending frame if there is room now (called on a timer and after each ack). */
97
98
  drain(): void;
98
- };
99
+ /** Drops the pending frame (the stream moved to another page); numbering and credit carry on. */
100
+ clear(): void;
101
+ /**
102
+ * The viewer opted in to frame credit: from now on frames go out as type 2 with a sequence number, and at most
103
+ * CREDIT_MAX_IN_FLIGHT of them may be unacknowledged. Without this call the sender behaves exactly as before.
104
+ */
105
+ enableCredit(): void;
106
+ /** The viewer has drawn frame `seq` (and so is done with every earlier one). Stale, duplicate and unknown acks are ignored. */
107
+ ack(seq: number): void;
108
+ }
109
+ /**
110
+ * Newest-frame-only sender: never queues more than one pending frame per viewer.
111
+ * Slow viewers skip frames instead of building a backlog. Two signals hold frames back: the socket's own buffer
112
+ * (bufferedAmount, where the runtime reports it) and, once negotiated, end-to-end frame credit from the viewer's acks
113
+ * (which also works where bufferedAmount is always 0: Workers' client sockets, a Durable Object relay).
114
+ */
115
+ declare function createLatestSender(conn: FrameSink, opts?: LatestSenderOptions): LatestSender;
99
116
 
100
117
  type SessionEvent = 'published' | 'notified' | 'viewer_joined' | 'viewer_left' | 'done' | 'cant_solve' | 'timeout' | 'cancel' | 'error';
101
118
  declare class InvalidTransitionError extends Error {
package/dist/index.js CHANGED
@@ -550,24 +550,64 @@ function safeInput(msg) {
550
550
  }
551
551
 
552
552
  // src/stream/latest.ts
553
+ import { FRAME_SEQ_MAX, withFrameSeq } from "@velmlabs/unstuck-protocol";
554
+ var CREDIT_MAX_IN_FLIGHT = 3;
555
+ var CREDIT_ACK_TIMEOUT_MS = 1e3;
556
+ var CREDIT_GRANT_MAX_MS = 8e3;
553
557
  function createLatestSender(conn, opts = {}) {
554
558
  const mark = opts.highWaterMark ?? 512 * 1024;
559
+ const now = opts.now ?? Date.now;
555
560
  let pending = null;
561
+ let credit = false;
562
+ let sentSeq = 0;
563
+ let ackedSeq = 0;
564
+ let since = 0;
565
+ let grantAfter = CREDIT_ACK_TIMEOUT_MS;
566
+ const room = () => {
567
+ if (!(conn.bufferedAmount < mark)) return false;
568
+ if (!credit || sentSeq - ackedSeq < CREDIT_MAX_IN_FLIGHT) return true;
569
+ if (now() - since < grantAfter) return false;
570
+ ackedSeq = sentSeq - CREDIT_MAX_IN_FLIGHT + 1;
571
+ grantAfter = Math.min(grantAfter * 2, CREDIT_GRANT_MAX_MS);
572
+ return true;
573
+ };
574
+ const send = (frame) => {
575
+ if (!credit) return conn.send(frame);
576
+ if (sentSeq === FRAME_SEQ_MAX) sentSeq = ackedSeq = 0;
577
+ conn.send(withFrameSeq(frame, ++sentSeq));
578
+ since = now();
579
+ };
580
+ const drain = () => {
581
+ if (pending && room()) {
582
+ const f = pending;
583
+ pending = null;
584
+ send(f);
585
+ }
586
+ };
556
587
  return {
557
588
  push(frame) {
558
- if (conn.bufferedAmount < mark) {
589
+ if (room()) {
559
590
  pending = null;
560
- conn.send(frame);
591
+ send(frame);
561
592
  } else {
562
593
  pending = frame;
563
594
  }
564
595
  },
565
- drain() {
566
- if (pending && conn.bufferedAmount < mark) {
567
- const f = pending;
568
- pending = null;
569
- conn.send(f);
570
- }
596
+ drain,
597
+ clear() {
598
+ pending = null;
599
+ },
600
+ enableCredit() {
601
+ if (credit) return;
602
+ credit = true;
603
+ since = now();
604
+ },
605
+ ack(seq) {
606
+ if (!credit || !Number.isInteger(seq) || seq <= ackedSeq || seq > sentSeq) return;
607
+ ackedSeq = seq;
608
+ since = now();
609
+ grantAfter = CREDIT_ACK_TIMEOUT_MS;
610
+ drain();
571
611
  }
572
612
  };
573
613
  }
@@ -700,6 +740,7 @@ function runTakeover(deps, cdp, opts) {
700
740
  let stopScreencast = null;
701
741
  let streamGen = 0;
702
742
  let sender = null;
743
+ let holderSender = null;
703
744
  let drainTimer = null;
704
745
  let leftTimer = null;
705
746
  let transportDown = false;
@@ -746,6 +787,7 @@ function runTakeover(deps, cdp, opts) {
746
787
  streamGen++;
747
788
  if (drainTimer) clearInterval(drainTimer);
748
789
  drainTimer = null;
790
+ sender?.clear();
749
791
  sender = null;
750
792
  const stop = stopScreencast;
751
793
  stopScreencast = null;
@@ -796,8 +838,8 @@ function runTakeover(deps, cdp, opts) {
796
838
  resumeKey = newSessionId();
797
839
  if (status === "waiting") go("viewer_joined");
798
840
  emit("viewer_joined");
799
- sendJson(conn, { t: "ready", reason: opts.reason, site: opts.site ?? "", expiresAt, resumeKey, ...vn ? { vn } : {} });
800
- sender = createLatestSender(conn);
841
+ sendJson(conn, { t: "ready", reason: opts.reason, site: opts.site ?? "", expiresAt, resumeKey, ...vn ? { vn } : {}, credit: 1 });
842
+ sender = holderSender = createLatestSender(conn, { now });
801
843
  if (lastFrame) sender.push(lastFrame);
802
844
  fieldFeed.onTargetChanged();
803
845
  if (!stopScreencast) await startStream();
@@ -832,7 +874,8 @@ function runTakeover(deps, cdp, opts) {
832
874
  await stopStream();
833
875
  lastFrame = null;
834
876
  if (!holder || isTerminal(status)) return;
835
- sender = createLatestSender(holder);
877
+ holderSender?.clear();
878
+ sender = holderSender;
836
879
  fieldFeed.onTargetChanged();
837
880
  await startStream();
838
881
  }
@@ -937,6 +980,10 @@ function runTakeover(deps, cdp, opts) {
937
980
  switch (msg.t) {
938
981
  case "ping":
939
982
  return sendJson(conn, { t: "pong" });
983
+ case "credit":
984
+ return void (conn === holder && holderSender?.enableCredit());
985
+ case "ack":
986
+ return void (conn === holder && holderSender?.ack(msg.seq));
940
987
  case "done":
941
988
  return finish("resolved");
942
989
  case "cant_solve": {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@velmlabs/unstuck-core",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "The Unstuck takeover engine core: screencast, input, sessions and transports, usable in Node or Cloudflare Workers.",
5
5
  "keywords": [
6
6
  "ai",
@@ -47,7 +47,7 @@
47
47
  },
48
48
  "dependencies": {
49
49
  "tldts": "^7.5.2",
50
- "@velmlabs/unstuck-protocol": "0.2.0"
50
+ "@velmlabs/unstuck-protocol": "0.2.1"
51
51
  },
52
52
  "publishConfig": {
53
53
  "access": "public"