@threadedstack/wmd-web 0.1.12 → 0.1.14

package/src/net/wisp.js

@@ -24,6 +24,9 @@
 //   0xE4 wmd-dns        packet 0xE5 LOOKUP   qtype u16 | name utf8                     client -> server
 //                       packet 0xE6 ANSWER   rcode u8 | ttl u32 | count u8 | addresses | reason utf8
 //   0xE7 wmd-instance   (no packet)          client metadata: a 16-byte instance id
+//   0xE9 wmd-reason     packet 0xE8 REASON   kind u8 | until f64 | rule length u8 | rule | words
+//                                                            server -> client: why a refusal or slowdown,
+//                                                            and when it lifts (stream 0: the session)
 
 export const SUBPROTOCOL = 'wisp-v2'
 export const VERSION = { major: 2, minor: 0 }
@@ -33,14 +36,18 @@ export const INSTANCE_BYTES = 16
 
 export const PT = {
   CONNECT: 0x01, DATA: 0x02, CONTINUE: 0x03, CLOSE: 0x04, INFO: 0x05,
-  CREDIT: 0xe0, SHUTDOWN: 0xe3, LOOKUP: 0xe5, ANSWER: 0xe6,
+  CREDIT: 0xe0, SHUTDOWN: 0xe3, LOOKUP: 0xe5, ANSWER: 0xe6, REASON: 0xe8,
 }
 
 export const EXT = {
   UDP: 0x01, PASSWORD: 0x02, KEY: 0x03, MOTD: 0x04, CONFIRM: 0x05,
-  WMD_CREDIT: 0xe1, WMD_HALFCLOSE: 0xe2, WMD_DNS: 0xe4, WMD_INSTANCE: 0xe7,
+  WMD_CREDIT: 0xe1, WMD_HALFCLOSE: 0xe2, WMD_DNS: 0xe4, WMD_INSTANCE: 0xe7, WMD_REASON: 0xe9,
 }
 
+/** REASON kinds: a refusal (a CLOSE follows), a slowdown, and a slowdown that has lifted. */
+export const REASON_KIND = { REFUSED: 1, SLOWED: 2, CLEARED: 3 }
+const RULE_MAX = 64
+
 export const STREAM = { TCP: 0x01, UDP: 0x02 }
 
 /** CLOSE reasons (spec, plus the extension-specified auth reasons). */
@@ -121,6 +128,21 @@ export function lookupPacket(id, name, qtype) {
   return packet(PT.LOOKUP, id, p)
 }
 
+/** until: ms since 1970 UTC when the rule lifts, 0 when it has no time. */
+export function reasonPacket(id, kind, rule, until, words) {
+  if (!/^[\x20-\x7e]*$/.test(rule)) throw new RangeError('wisp: a rule name is ASCII')
+  if (rule.length > RULE_MAX) throw new RangeError(`wisp: a rule name is at most ${RULE_MAX} characters`)
+  const w = enc.encode(words || '')
+  const p = new Uint8Array(10 + rule.length + w.length)
+  const dv = new DataView(p.buffer)
+  p[0] = kind
+  dv.setFloat64(1, until || 0, true)
+  p[9] = rule.length
+  for (let i = 0; i < rule.length; i++) p[10 + i] = rule.charCodeAt(i)
+  p.set(w, 10 + rule.length)
+  return packet(PT.REASON, id, p)
+}
+
 /** addrs: arrays of 4 (A) or 16 (AAAA) bytes. */
 export function answerPacket(id, rcode, ttl, addrs = [], reason = '') {
   const d = enc.encode(reason)
@@ -181,6 +203,7 @@ export const ext = {
   },
   wmdHalfclose: () => ({ id: EXT.WMD_HALFCLOSE, data: Uint8Array.of(WMD_EXT_VERSION) }),
   wmdDns: () => ({ id: EXT.WMD_DNS, data: Uint8Array.of(WMD_EXT_VERSION) }),
+  wmdReason: () => ({ id: EXT.WMD_REASON, data: Uint8Array.of(WMD_EXT_VERSION) }),
   /** The client sends its 16-byte id; the server lists the extension with no id. */
   wmdInstance(idBytes) {
     if (!idBytes) return { id: EXT.WMD_INSTANCE, data: Uint8Array.of(WMD_EXT_VERSION) }
@@ -229,6 +252,7 @@ export function readExt(e, from) {
       return { version: d[0] }
     case EXT.WMD_HALFCLOSE:
     case EXT.WMD_DNS:
+    case EXT.WMD_REASON:
       if (d.length < 1) return { error: 'wmd extension without a version' }
       return { version: d[0] }
     case EXT.WMD_INSTANCE:
@@ -307,6 +331,16 @@ export function parse(u8) {
       m.count = p[5]
       m.rest = p.subarray(6) // the addresses (their size depends on the query), then the reason
       break
+    case PT.REASON: {
+      if (p.length < 10 || p.length < 10 + p[9]) return bad('REASON too short')
+      m.kind = p[0]
+      m.until = dv.getFloat64(6, true)
+      m.rule = String.fromCharCode(...p.subarray(10, 10 + p[9]))
+      const w = text(p.subarray(10 + p[9]))
+      if (w === null) return bad('REASON words are not UTF-8')
+      m.words = w
+      break
+    }
     case PT.INFO: {
       if (p.length < 2) return bad('INFO too short')
       m.version = { major: p[0], minor: p[1] }
@@ -343,15 +377,15 @@ export function answerAddrs(m, qtype) {
 // Both machines are pure: feed packets in, get packets to send and an outcome out. The caller
 // owns the WebSocket and the timers.
 
-const WMD_EXTS = new Set([EXT.WMD_CREDIT, EXT.WMD_HALFCLOSE, EXT.WMD_DNS, EXT.WMD_INSTANCE])
+const WMD_EXTS = new Set([EXT.WMD_CREDIT, EXT.WMD_HALFCLOSE, EXT.WMD_DNS, EXT.WMD_INSTANCE, EXT.WMD_REASON])
 
 /**
  * The client side. `exts` are the extensions the client offers (built with `ext.*`, without
  * password auth); `password` is {user, pass} or null.
  *
  * step(pkt) returns {send: Uint8Array[], done?: {version: 1|2, buffer, server: Map, common: Set,
- * motd}, fail?: {reason, words, state}}. state is one of 'auth-required', 'auth-refused',
- * 'incompatible', 'protocol'.
+ * motd}, fail?: {reason, words, state, rule?, until?}}. state is one of 'auth-required', 'auth-refused',
+ * 'incompatible', 'protocol', or 'limited' when the relay said why (wmd-reason).
  */
 export class ClientHandshake {
   constructor({ exts = [], password = null } = {}) {
@@ -412,7 +446,19 @@ export class ClientHandshake {
     }
     if (this.state === 'wait-continue') {
       if (m.id !== 0) return fail('protocol', CLOSE.UNKNOWN, 'the relay sent a stream packet before the handshake ended')
-      if (m.type === PT.CLOSE) return fail(closeState(m.reason), m.reason, closeWords(m.reason))
+      if (m.type === PT.REASON) {
+        this.why = { rule: m.rule, until: m.until, words: m.words }
+        return { send: [] }
+      }
+      if (m.type === PT.CLOSE) {
+        if (this.why) {
+          const r = fail('limited', m.reason, this.why.words || closeWords(m.reason))
+          r.fail.rule = this.why.rule
+          r.fail.until = this.why.until
+          return r
+        }
+        return fail(closeState(m.reason), m.reason, closeWords(m.reason))
+      }
       if (m.type !== PT.CONTINUE) return fail('protocol', CLOSE.UNKNOWN, 'the relay did not answer INFO with CONTINUE')
       this.state = 'done'
       const common = new Set(this.exts.filter((e) => this.server.has(e.id)).map((e) => e.id))