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.
- package/README.md +117 -31
- package/bin/portpreview.mjs +5 -61
- package/lib/cli-main.mjs +40 -0
- package/lib/client-info.mjs +83 -0
- package/lib/config-cli.mjs +65 -0
- package/lib/config.mjs +29 -8
- package/lib/geo.mjs +84 -0
- package/lib/http-stream.mjs +134 -0
- package/lib/index.mjs +10 -7
- package/lib/protocol.mjs +145 -10
- package/lib/tunnel-client.mjs +428 -57
- package/lib/user-config.mjs +81 -0
- package/package.json +20 -13
|
@@ -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
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
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,
|
|
12
|
+
export { publicUrl, PROTOCOL_VERSION, MAX_BODY_BYTES } from './protocol.mjs'
|
package/lib/protocol.mjs
CHANGED
|
@@ -1,6 +1,14 @@
|
|
|
1
|
-
/**
|
|
1
|
+
/** Wire format shared by CLI client and gateway. */
|
|
2
2
|
|
|
3
|
-
export const PROTOCOL_VERSION =
|
|
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 {
|
|
15
|
-
* @
|
|
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
|
-
|
|
18
|
-
|
|
57
|
+
function stripAttachedFields(header) {
|
|
58
|
+
const { body: _body, data: _data, ...rest } = header
|
|
59
|
+
return rest
|
|
19
60
|
}
|
|
20
61
|
|
|
21
62
|
/**
|
|
22
|
-
* @param {string
|
|
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
|
|
27
|
-
|
|
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
|
-
|
|
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
|
+
}
|