portpreview 0.1.0 → 0.2.0

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.
@@ -0,0 +1,134 @@
1
+ import { attachedBody, encodeFrame, send, STREAM_CHUNK_BYTES, STREAM_WINDOW_BYTES } from './protocol.mjs'
2
+
3
+ /** Bounded HTTP pipe. Credits return only after the destination flushes its write.
4
+ * The readable is pulled in <=64KiB pieces; at most 256KiB is in flight per direction.
5
+ * Neither byte count nor elapsed transfer duration limits a stream.
6
+ */
7
+ export function createHttpStream({ ws, id, outgoing, onError, onEnd, onSentEnd, onSend, onReceive, idleTimeoutMs = 120_000, destroyOnError = true }) {
8
+ const incoming = outgoing === 'request' ? 'response' : 'request'
9
+ let source, destination, credit = 0, available = STREAM_WINDOW_BYTES
10
+ let pumping = false, sentEnd = false, receivedEnd = false, closed = false
11
+ let timer
12
+ const activity = () => {
13
+ clearTimeout(timer)
14
+ if (idleTimeoutMs > 0 && !closed) {
15
+ timer = setTimeout(() => fail(new Error('HTTP stream idle timeout')), idleTimeoutMs)
16
+ timer.unref()
17
+ }
18
+ }
19
+ const control = (message) => {
20
+ if (ws.readyState !== ws.OPEN) throw new Error('Tunnel offline')
21
+ send(ws, { ...message, id })
22
+ activity()
23
+ }
24
+ const fail = (error, notify = true) => {
25
+ if (closed) return
26
+ if (notify && ws.readyState === ws.OPEN) send(ws, { type: 'http_cancel', id, reason: error.message })
27
+ stop()
28
+ onError?.(error)
29
+ if (destroyOnError) { source?.destroy(); destination?.destroy() }
30
+ }
31
+ function stop() {
32
+ if (closed) return
33
+ closed = true
34
+ clearTimeout(timer)
35
+ source?.off('readable', pump)
36
+ source?.off('end', pump)
37
+ source?.off('error', fail)
38
+ // Aborted IncomingMessages can emit ECONNRESET after their aborted event.
39
+ source?.once('error', () => {})
40
+ destination?.off('error', fail)
41
+ }
42
+ async function pump() {
43
+ if (pumping || closed || sentEnd || !source) return
44
+ pumping = true
45
+ try {
46
+ source.read(0)
47
+ while (!closed && credit > 0) {
48
+ // IncomingMessage.read(n) may wait for n bytes. read() then split would
49
+ // retain an arbitrarily sized custom source chunk; cap the pull instead.
50
+ const size = Math.min(credit, STREAM_CHUNK_BYTES, source.readableLength)
51
+ if (!size) break
52
+ const chunk = source.read(size)
53
+ if (!chunk) break
54
+ credit -= chunk.length
55
+ onSend?.(chunk)
56
+ const frame = encodeFrame({ type: 'http_data', id, direction: outgoing }, chunk)
57
+ await new Promise((resolve, reject) => ws.send(frame, { binary: true }, (error) => error ? reject(error) : resolve()))
58
+ activity()
59
+ }
60
+ if (!closed && source.readableEnded && source.readableLength === 0) {
61
+ sentEnd = true
62
+ control({ type: 'http_end', direction: outgoing })
63
+ onSentEnd?.()
64
+ }
65
+ } catch (error) { fail(error) }
66
+ finally { pumping = false }
67
+ }
68
+ activity()
69
+ return {
70
+ setSource(readable) {
71
+ source = readable
72
+ readable.on('readable', pump)
73
+ readable.on('end', pump)
74
+ readable.on('error', fail)
75
+ void pump()
76
+ },
77
+ setDestination(writable) {
78
+ destination = writable
79
+ writable.on('error', fail)
80
+ control({ type: 'http_credit', direction: incoming, bytes: STREAM_WINDOW_BYTES })
81
+ },
82
+ handle(message) {
83
+ if (closed) return
84
+ activity()
85
+ if (message.type === 'http_cancel') { fail(new Error(String(message.reason ?? 'HTTP stream cancelled')), false); return }
86
+ if (message.type === 'http_credit') {
87
+ if (message.direction !== outgoing || !Number.isInteger(message.bytes) || message.bytes <= 0 || credit + message.bytes > STREAM_WINDOW_BYTES) {
88
+ fail(new Error('Invalid HTTP stream credit')); return
89
+ }
90
+ credit += message.bytes
91
+ void pump()
92
+ } else if (message.type === 'http_data') {
93
+ const chunk = attachedBody(message)
94
+ if (message.direction !== incoming || !destination || receivedEnd || !chunk.length || chunk.length > STREAM_CHUNK_BYTES || chunk.length > available) {
95
+ fail(new Error('Invalid HTTP stream data')); return
96
+ }
97
+ available -= chunk.length
98
+ onReceive?.(chunk)
99
+ destination.write(chunk, (error) => {
100
+ if (error) { fail(error); return }
101
+ if (closed || receivedEnd) return
102
+ available += chunk.length
103
+ try { control({ type: 'http_credit', direction: incoming, bytes: chunk.length }) } catch (error) { fail(error) }
104
+ })
105
+ } else if (message.type === 'http_end') {
106
+ if (message.direction !== incoming || !destination || receivedEnd) { fail(new Error('Invalid HTTP stream end')); return }
107
+ receivedEnd = true
108
+ destination.end(() => onEnd?.())
109
+ }
110
+ },
111
+ cancel: fail,
112
+ stop,
113
+ touch: activity,
114
+ }
115
+ }
116
+
117
+ /** Capture only a preview; never retain the full streaming body. */
118
+ export function createBodyPreview(limit = 64 * 1024) {
119
+ const chunks = []
120
+ let retained = 0, bytes = 0n
121
+ return {
122
+ add(chunk) {
123
+ bytes += BigInt(chunk.length)
124
+ if (retained < limit) {
125
+ const part = chunk.subarray(0, limit - retained)
126
+ chunks.push(Buffer.from(part))
127
+ retained += part.length
128
+ }
129
+ },
130
+ get bytes() { return bytes <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(bytes) : bytes.toString() },
131
+ get truncated() { return bytes > BigInt(retained) },
132
+ body() { return Buffer.concat(chunks, retained) },
133
+ }
134
+ }
package/lib/index.mjs CHANGED
@@ -1,9 +1,12 @@
1
+ export { parseArgs, printHelp, DEFAULT_GATEWAY_URL, DEFAULT_TUNNEL_DOMAIN, fail } from './config.mjs'
2
+ export { printConfigHelp, runConfigCommand } from './config-cli.mjs'
1
3
  export {
2
- DEFAULT_GATEWAY_URL,
3
- DEFAULT_TUNNEL_DOMAIN,
4
- fail,
5
- parseArgs,
6
- printHelp,
7
- } from './config.mjs'
4
+ assertValidToken,
5
+ clearStoredToken,
6
+ defaultConfigPath,
7
+ readStoredToken,
8
+ readUserConfig,
9
+ saveToken,
10
+ } from './user-config.mjs'
8
11
  export { openTunnel, waitForLocalPort } from './tunnel-client.mjs'
9
- export { PROTOCOL_VERSION, publicUrl } from './protocol.mjs'
12
+ export { publicUrl, PROTOCOL_VERSION, MAX_BODY_BYTES } from './protocol.mjs'
package/lib/protocol.mjs CHANGED
@@ -1,6 +1,14 @@
1
- /** JSON wire format between the CLI client and the gateway. */
1
+ /** Wire format shared by CLI client and gateway. */
2
2
 
3
- export const PROTOCOL_VERSION = 1
3
+ export const PROTOCOL_VERSION = 3
4
+ export const LEGACY_PROTOCOL_VERSION = 2
5
+ export const STREAM_CHUNK_BYTES = 64 * 1024
6
+ export const STREAM_WINDOW_BYTES = 256 * 1024
7
+
8
+ /** Legacy v2 attached-body cap; v3 HTTP uses bounded chunks with no total body cap. */
9
+ export const MAX_BODY_BYTES = 1024 * 1024
10
+ export const MAX_HEADER_BYTES = 256 * 1024
11
+ export const MAX_FRAME_BYTES = 4 + MAX_HEADER_BYTES + MAX_BODY_BYTES
4
12
 
5
13
  /**
6
14
  * @param {unknown} value
@@ -11,22 +19,141 @@ export function isObject(value) {
11
19
  }
12
20
 
13
21
  /**
14
- * @param {import('ws').WebSocket} ws
15
- * @param {Record<string, unknown>} message
22
+ * @param {unknown} data
23
+ * @returns {Buffer}
24
+ */
25
+ export function toBuffer(data) {
26
+ if (data == null) return Buffer.alloc(0)
27
+ if (Buffer.isBuffer(data)) return data
28
+ if (typeof data === 'string') return Buffer.from(data)
29
+ if (data instanceof ArrayBuffer) return Buffer.from(data)
30
+ if (ArrayBuffer.isView(data)) {
31
+ return Buffer.from(data.buffer, data.byteOffset, data.byteLength)
32
+ }
33
+ if (Array.isArray(data)) return Buffer.concat(data.map((part) => toBuffer(part)))
34
+ return Buffer.from(data)
35
+ }
36
+
37
+ /**
38
+ * @param {unknown} value
39
+ * @param {number} [maxBytes]
40
+ */
41
+ export function clipBody(value, maxBytes = MAX_BODY_BYTES) {
42
+ const body = toBuffer(value)
43
+ if (body.length <= maxBytes) {
44
+ return { body, truncated: false, originalLength: body.length }
45
+ }
46
+ return {
47
+ body: body.subarray(0, maxBytes),
48
+ truncated: true,
49
+ originalLength: body.length,
50
+ }
51
+ }
52
+
53
+ /**
54
+ * @param {Record<string, unknown>} header
55
+ * @returns {Record<string, unknown>}
16
56
  */
17
- export function send(ws, message) {
18
- ws.send(JSON.stringify(message))
57
+ function stripAttachedFields(header) {
58
+ const { body: _body, data: _data, ...rest } = header
59
+ return rest
19
60
  }
20
61
 
21
62
  /**
22
- * @param {string | Buffer | ArrayBuffer} data
63
+ * @param {Record<string, unknown>} headers
64
+ * @param {number} length
65
+ * @param {boolean} truncated
23
66
  * @returns {Record<string, unknown>}
24
67
  */
68
+ function withBodyHeaders(headers, length, truncated) {
69
+ /** @type {Record<string, unknown>} */
70
+ const next = {}
71
+ for (const [key, value] of Object.entries(headers)) {
72
+ const name = key.toLowerCase()
73
+ if (name === 'content-length' || name === 'transfer-encoding') continue
74
+ next[key] = value
75
+ }
76
+ next['content-length'] = String(length)
77
+ if (truncated) next['x-portpreview-truncated'] = '1'
78
+ return next
79
+ }
80
+
81
+ /**
82
+ * Length-prefixed binary frame: [uint32be jsonLen][utf8 json][raw body].
83
+ * JSON holds control fields only; the body is never base64.
84
+ *
85
+ * @param {Record<string, unknown>} header
86
+ * @param {unknown} [body]
87
+ */
88
+ export function encodeFrame(header, body) {
89
+ if (header.type === 'http_data' && toBuffer(body).length > STREAM_CHUNK_BYTES) throw new Error('Streaming chunk too large')
90
+ if (header.type === 'ws_data' && toBuffer(body).length > MAX_BODY_BYTES) throw new Error('WebSocket message too large')
91
+ const clipped = clipBody(body)
92
+ const payload = stripAttachedFields(header)
93
+ const truncated = Boolean(payload.truncated) || clipped.truncated
94
+ if (truncated) {
95
+ payload.truncated = true
96
+ payload.originalLength = Number(payload.originalLength ?? clipped.originalLength)
97
+ }
98
+
99
+ if (
100
+ (payload.type === 'request' || payload.type === 'response') &&
101
+ isObject(payload.headers)
102
+ ) {
103
+ payload.headers = withBodyHeaders(
104
+ /** @type {Record<string, unknown>} */ (payload.headers),
105
+ clipped.body.length,
106
+ truncated,
107
+ )
108
+ }
109
+
110
+ const headerBuf = Buffer.from(JSON.stringify(payload), 'utf8')
111
+ if (headerBuf.length > MAX_HEADER_BYTES) {
112
+ throw new Error('Control header too large')
113
+ }
114
+
115
+ const frame = Buffer.allocUnsafe(4 + headerBuf.length + clipped.body.length)
116
+ frame.writeUInt32BE(headerBuf.length, 0)
117
+ headerBuf.copy(frame, 4)
118
+ clipped.body.copy(frame, 4 + headerBuf.length)
119
+ return frame
120
+ }
121
+
122
+ /**
123
+ * @param {import('ws').WebSocket} ws
124
+ * @param {Record<string, unknown>} header
125
+ * @param {unknown} [body]
126
+ */
127
+ export function send(ws, header, body) {
128
+ ws.send(encodeFrame(header, body), { binary: true })
129
+ }
130
+
131
+ /**
132
+ * @param {unknown} data
133
+ * @returns {Record<string, unknown> & { body: Buffer }}
134
+ */
25
135
  export function parseMessage(data) {
26
- const text = typeof data === 'string' ? data : Buffer.from(data).toString('utf8')
27
- const parsed = JSON.parse(text)
136
+ const buf = toBuffer(data)
137
+ if (buf.length < 4 || buf[0] === 0x7b) {
138
+ throw new Error('Invalid message payload')
139
+ }
140
+
141
+ const headerLen = buf.readUInt32BE(0)
142
+ if (headerLen < 2 || headerLen > MAX_HEADER_BYTES || 4 + headerLen > buf.length) {
143
+ throw new Error('Invalid message header')
144
+ }
145
+
146
+ const parsed = JSON.parse(buf.subarray(4, 4 + headerLen).toString('utf8'))
28
147
  if (!isObject(parsed)) throw new Error('Invalid message payload')
29
- return parsed
148
+ parsed.body = buf.subarray(4 + headerLen)
149
+ return /** @type {Record<string, unknown> & { body: Buffer }} */ (parsed)
150
+ }
151
+
152
+ /**
153
+ * @param {Record<string, unknown>} message
154
+ */
155
+ export function attachedBody(message) {
156
+ return Buffer.isBuffer(message.body) ? message.body : Buffer.alloc(0)
30
157
  }
31
158
 
32
159
  /**
@@ -47,3 +174,11 @@ export function localGatewayHttpUrl(subdomain, tunnelDomain) {
47
174
  }
48
175
  return publicUrl(subdomain, tunnelDomain)
49
176
  }
177
+
178
+ /** Normalize received close details before passing them to ws. */
179
+ export function closeWebSocket(socket, code = 1000, reason = '') {
180
+ const valid = [1000, 1001, 1002, 1003, 1007, 1008, 1009, 1010, 1011, 1012, 1013, 1014].includes(Number(code)) || (Number.isInteger(Number(code)) && Number(code) >= 3000 && Number(code) <= 4999)
181
+ let text = String(reason ?? '')
182
+ while (Buffer.byteLength(text) > 123) text = text.slice(0, -1)
183
+ socket.close(valid ? Number(code) : 1000, text)
184
+ }