@oxidezap/baileyrs 0.1.2 → 0.2.0

package/README.md

@@ -27,6 +27,14 @@ so existing integrations can migrate with minimal changes. See
 | Key management | JS auth state | Rust `PersistenceManager` |
 | Auto-reconnect | Manual `startSock()` loop | Transient drops retried in Rust (fibonacci backoff); terminal ones still yours |
 
+Compatibility is checked rather than assumed: a declaration audit against
+upstream's `.d.ts`, a wire-fidelity audit of the send path, ~50 behavioural
+compatibility suites, and a
+[differential fuzz suite](src/__fuzz__/README.md) that generates its own inputs
+from the proto schema and compares the two libraries directly. Differences the
+fuzzers find are recorded with a reason and a review date, and known open ones
+are listed in `src/__fuzz__/harness/divergence.ts`.
+
 ## Documentation
 
 The full API reference and guides live in the
@@ -212,6 +220,11 @@ A few behaviors that differ from upstream — almost always to your advantage:
   | anything else | reconnect, after a short delay |
 
   `Example/example.ts` implements exactly this.
+- **`connecting` is not a short state here.** The engine's backoff grows with
+  each consecutive failure, so a single `connecting` can stand for minutes of
+  downtime with nothing else emitted in between. See
+  [When `connecting` lasts minutes](#when-connecting-lasts-minutes): a
+  readiness timeout written for upstream's `connecting` misreads this one.
 - **No `getMessage` / `cachedGroupMetadata` polyfill required.** The Rust
   side caches group metadata and message keys natively. You can still pass
   them — they're respected as overrides — but they're optional.
@@ -224,6 +237,53 @@ A few behaviors that differ from upstream — almost always to your advantage:
   See [Bridge state in your key store](#bridge-state-in-your-key-store) — this
   one can break a boot path, so it has its own section.
 
+### When `connecting` lasts minutes
+
+Upstream Baileys emits `connecting` once per socket, and it resolves to `open`
+or `close` within seconds, because upstream never retries on its own. On
+baileyrs the same value also covers every drop the engine is retrying, and the
+backoff between those retries climbs with each consecutive failure.
+
+Here is what that costs on a rate-limited account. Four consecutive
+`429 rate-overlimit`, measured against the production reconnect path:
+
+| failure | next attempt in | offline so far |
+| --- | --- | --- |
+| `429` #1 | 8.4s | 8.4s |
+| `429` #2 | 146.2s | 154.6s |
+| `429` #3 | 813.9s | 968.5s |
+| `429` #4 | 903.5s | 1872.0s |
+
+About 16 minutes offline once the third retry delay has run, and about 31 once
+the fourth has. For all of it the consumer sees exactly **one**
+`connection: 'connecting'`: no `lastDisconnect`, no status code, no repeat.
+`isConnected` and `isLoggedIn` are both `false` throughout, exactly as they are
+during a first connection, so neither tells you a retry is scheduled.
+
+**Do not arm a readiness timeout on `connecting`, and above all do not restart
+the process when one expires.** The backoff counter lives in the Rust client
+that your socket owns, so it dies with the process. The next boot starts a new
+attempt immediately, replays the whole startup burst against a server that just
+asked for less traffic, and earns the next `429` sooner. Restarting is the
+single worst answer to a rate limit, and an upstream-shaped readiness timeout
+leads straight to it.
+
+What to do instead:
+
+- Treat `open` and `close` as the only decision points. `connecting` carries no
+  failure to react to, and it is never a reason to build a second socket. Only
+  `close` is.
+- Read `connecting` in context: after an `open` it means the engine is retrying
+  a drop it owns and will keep retrying; with no `open` before it, it is a first
+  connection still being established. Neither one is stuck.
+- If you need a liveness watchdog anyway, budget it well past the ladder above,
+  tens of minutes rather than seconds, and have it alert a human instead of
+  killing the process. A shorter one fires on a backoff that was about to
+  succeed.
+- Fix the cause on your side: send less. The engine restores the connection,
+  but it does not pace your traffic, and the traffic is what earned the `429`.
+  Queueing, throttling and deferral are yours to decide, the same as upstream.
+
 ### Bridge state in your key store
 
 Upstream Baileys keeps engine state in `creds` (persisted by `saveCreds`) and

package/lib/Bridge/primitives.d.ts

@@ -46,15 +46,61 @@ export declare const bridgeJidToAddressString: (j: BridgeJid) => string;
 /** Validate and stringify a signaling JID without discarding its device. */
 export declare const asJidAddressString: (x: unknown) => string | undefined;
 /**
- * Coerce a timestamp value into unix seconds. Accepts both numbers and ISO
- * strings — the bridge serializes `DateTime<Utc>` as ISO unless explicitly
- * typed with `ts_seconds`, so being lenient here insulates us from drift.
+ * Coerce a timestamp value into unix seconds. Accepts both numbers and RFC 3339
+ * strings — the bridge serializes `DateTime<Utc>` as a string unless the field
+ * names one of chrono's `ts_*` modules, so being lenient about which of the two
+ * arrives insulates us from drift.
  */
 export declare const toUnixSeconds: (raw: unknown) => number;
+/**
+ * Same as `toUnixSeconds`, but absence stays absent.
+ *
+ * The optional timestamps — `last_seen`, a server ack's `t`, an app-state
+ * mutation's own time — mean "the server did not say" when missing, which is
+ * not the same claim as the epoch.
+ */
+export declare const asUnixSeconds: (raw: unknown) => number | undefined;
+/**
+ * A 64-bit proto field, however the bridge chose to carry it.
+ *
+ * A protobuf `int64` reaches JavaScript as a protobufjs `Long`
+ * (`{ low, high, unsigned }`, sometimes with `toNumber`), because 64 bits do
+ * not fit a JS number. A plain number is accepted too: the same field arrived
+ * that way while these payloads crossed through serde, and a bridge is free to
+ * go back to it.
+ *
+ * Reconstructed from the pair only when `high` is 0 or -1, the range a JS
+ * number represents exactly. Beyond that the value would be silently rounded,
+ * and a wrong timestamp is worse than a missing one.
+ */
+export declare const asInt64: (x: unknown) => number | undefined;
+/**
+ * A `std::time::Duration`, in whole seconds.
+ *
+ * Serde writes one as `{ secs, nanos }`, and the bridge's own declaration for
+ * these fields says `number` — so a consumer reading the declared type off a
+ * plain-serialized event gets an object where it expected a count. Both are
+ * accepted here rather than betting on which side moves first; sub-second
+ * precision is dropped because every caller of this is a ban or a backoff
+ * measured in seconds.
+ */
+export declare const asDurationSeconds: (x: unknown) => number | undefined;
 /**
  * Lowercase a discriminator string defensively — handles both the current
  * lowercase wire-tag form and any legacy PascalCase form an older bridge
  * might still emit.
  */
 export declare const normalizeDiscriminator: (x: unknown) => string | undefined;
+/**
+ * Turn a duration in seconds into the unix-seconds instant it ends at.
+ *
+ * The bridge reports a temporary ban the way the wire states it, as how long
+ * the ban lasts. Consumers are promised the deadline: the socket formats it
+ * with `new Date(expire * 1000)` and a reconnect policy subtracts `Date.now()`
+ * from it, so handing either of them a relative count puts the ban in 1970 and
+ * lets a bot retry immediately.
+ */
+export declare const absoluteFromDuration: (seconds: number | undefined) => number | undefined;
+/** Wire collection names and the like: anything that is not a string is not one. */
+export declare const asStringArray: (x: unknown) => string[];
 //# sourceMappingURL=primitives.d.ts.map

package/lib/Bridge/primitives.js

@@ -46,20 +46,116 @@ export const asJidAddressString = (x) => {
     return j ? bridgeJidToAddressString(j) : undefined;
 };
 /**
- * Coerce a timestamp value into unix seconds. Accepts both numbers and ISO
- * strings — the bridge serializes `DateTime<Utc>` as ISO unless explicitly
- * typed with `ts_seconds`, so being lenient here insulates us from drift.
+ * The shape chrono writes for a `DateTime` it serializes plainly.
+ *
+ * Checked before parsing because `Date.parse` accepts far more than that, and
+ * silently: `Date.parse('0')` is the year 2000, so a numeric-string sentinel
+ * would become a plausible, wrong instant instead of being refused.
+ */
+const RFC_3339 = /^\d{4}-\d{2}-\d{2}[Tt ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:[Zz]|[+-]\d{2}:?\d{2})$/;
+const MONTH_LENGTHS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+/** Gregorian, so a century is only a leap year when it divides by 400. */
+const daysInMonth = (year, month) => month === 2 && year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0) ? 29 : (MONTH_LENGTHS[month - 1] ?? 0);
+/** Fixed-width digits at a known offset, which the pattern above guarantees. */
+const digits2 = (raw, at) => (raw.charCodeAt(at) - 48) * 10 + (raw.charCodeAt(at + 1) - 48);
+const parseRfc3339Seconds = (raw) => {
+    // `test` rather than `exec`: the components come out of fixed offsets
+    // below, and asking the engine for capture groups costs more than the whole
+    // rest of this function.
+    if (!RFC_3339.test(raw))
+        return undefined;
+    // `Date.parse` refuses month 13, hour 25 and second 61, but rolls a day
+    // past the end of its month forward instead: `2023-02-30` comes back as
+    // March 2. That is the one component worth checking here.
+    const year = digits2(raw, 0) * 100 + digits2(raw, 2);
+    if (digits2(raw, 8) > daysInMonth(year, digits2(raw, 5)))
+        return undefined;
+    // The other one it rolls forward rather than refusing: RFC 3339 stops the
+    // hour at 23, while `2023-11-14T24:00:00Z` parses as midnight the next day.
+    if (digits2(raw, 11) > 23)
+        return undefined;
+    const ms = Date.parse(raw);
+    return Number.isFinite(ms) ? Math.floor(ms / 1000) : undefined;
+};
+/**
+ * Coerce a timestamp value into unix seconds. Accepts both numbers and RFC 3339
+ * strings — the bridge serializes `DateTime<Utc>` as a string unless the field
+ * names one of chrono's `ts_*` modules, so being lenient about which of the two
+ * arrives insulates us from drift.
  */
 export const toUnixSeconds = (raw) => {
     if (typeof raw === 'number' && Number.isFinite(raw))
         return raw;
-    if (typeof raw === 'string') {
-        const ms = Date.parse(raw);
-        if (Number.isFinite(ms))
-            return Math.floor(ms / 1000);
-    }
+    if (typeof raw === 'string')
+        return parseRfc3339Seconds(raw) ?? 0;
     return 0;
 };
+/**
+ * Same as `toUnixSeconds`, but absence stays absent.
+ *
+ * The optional timestamps — `last_seen`, a server ack's `t`, an app-state
+ * mutation's own time — mean "the server did not say" when missing, which is
+ * not the same claim as the epoch.
+ */
+export const asUnixSeconds = (raw) => {
+    if (typeof raw === 'number' && Number.isFinite(raw))
+        return raw;
+    if (typeof raw === 'string')
+        return parseRfc3339Seconds(raw);
+    return undefined;
+};
+/**
+ * A 64-bit proto field, however the bridge chose to carry it.
+ *
+ * A protobuf `int64` reaches JavaScript as a protobufjs `Long`
+ * (`{ low, high, unsigned }`, sometimes with `toNumber`), because 64 bits do
+ * not fit a JS number. A plain number is accepted too: the same field arrived
+ * that way while these payloads crossed through serde, and a bridge is free to
+ * go back to it.
+ *
+ * Reconstructed from the pair only when `high` is 0 or -1, the range a JS
+ * number represents exactly. Beyond that the value would be silently rounded,
+ * and a wrong timestamp is worse than a missing one.
+ */
+export const asInt64 = (x) => {
+    if (typeof x === 'number')
+        return Number.isSafeInteger(x) ? x : undefined;
+    if (!isObject(x))
+        return undefined;
+    if (typeof x.toNumber === 'function') {
+        const value = x.toNumber();
+        // `Long.toNumber` rounds rather than refusing, so a value past 2^53
+        // comes back finite and wrong. Only exact ones are worth reporting.
+        return typeof value === 'number' && Number.isSafeInteger(value) ? value : undefined;
+    }
+    const low = x.low;
+    if (typeof low !== 'number')
+        return undefined;
+    const high = typeof x.high === 'number' ? x.high : 0;
+    // The pair is `high * 2^32 + (low >>> 0)`, signed through `high`. Reading
+    // the halves separately gets the sign right only by accident: `high: -1`
+    // with `low: 0` is -2^32, not 0.
+    const value = high * 2 ** 32 + (low >>> 0);
+    return Number.isSafeInteger(value) ? value : undefined;
+};
+/**
+ * A `std::time::Duration`, in whole seconds.
+ *
+ * Serde writes one as `{ secs, nanos }`, and the bridge's own declaration for
+ * these fields says `number` — so a consumer reading the declared type off a
+ * plain-serialized event gets an object where it expected a count. Both are
+ * accepted here rather than betting on which side moves first; sub-second
+ * precision is dropped because every caller of this is a ban or a backoff
+ * measured in seconds.
+ */
+export const asDurationSeconds = (x) => {
+    if (typeof x === 'number')
+        return Number.isFinite(x) ? x : undefined;
+    if (!isObject(x))
+        return undefined;
+    const secs = asInt64(x.secs);
+    return secs === undefined ? undefined : secs;
+};
 /**
  * Lowercase a discriminator string defensively — handles both the current
  * lowercase wire-tag form and any legacy PascalCase form an older bridge
@@ -69,4 +165,26 @@ export const normalizeDiscriminator = (x) => {
     const s = asString(x);
     return s ? s.toLowerCase() : undefined;
 };
+/**
+ * Turn a duration in seconds into the unix-seconds instant it ends at.
+ *
+ * The bridge reports a temporary ban the way the wire states it, as how long
+ * the ban lasts. Consumers are promised the deadline: the socket formats it
+ * with `new Date(expire * 1000)` and a reconnect policy subtracts `Date.now()`
+ * from it, so handing either of them a relative count puts the ban in 1970 and
+ * lets a bot retry immediately.
+ */
+export const absoluteFromDuration = (seconds) => {
+    if (seconds === undefined)
+        return undefined;
+    const deadline = Math.floor(Date.now() / 1000) + seconds;
+    // A deadline `Date` cannot hold is worse than none: the socket formats this
+    // with `new Date(expire * 1000).toISOString()`, which throws a RangeError
+    // past ±8.64e15 ms and would take the event dispatch down with it.
+    return Number.isSafeInteger(deadline) && Math.abs(deadline) <= MAX_DATE_SECONDS ? deadline : undefined;
+};
+/** `Date` holds ±8.64e15 ms, which is this many whole seconds. */
+const MAX_DATE_SECONDS = 8640000000000;
+/** Wire collection names and the like: anything that is not a string is not one. */
+export const asStringArray = (x) => Array.isArray(x) ? x.filter((item) => typeof item === 'string') : [];
 //# sourceMappingURL=primitives.js.map