@twinsearth/dsh-2xray 0.0.0-stage → 0.1.0

package/test/binary.test.js

@@ -0,0 +1,103 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { join } from 'node:path'
+import { BinaryError, resolveBinary } from '../lib/binary.js'
+import { normalizeConfig } from '../lib/config.js'
+
+const packageRoot = join('C:', 'plugins', 'dsh-2xray')
+const dataDir = join('C:', 'users', 'me', '.dsh', 'xray-proxy')
+const exe = process.platform === 'win32' ? 'xray.exe' : 'xray'
+const bundled = join(packageRoot, 'bin', exe)
+const managed = join(dataDir, 'bin', exe)
+
+function config(overrides = {}) {
+  return normalizeConfig({ enabled: true, ...overrides }).config
+}
+
+function only(...paths) {
+  return (candidate) => paths.includes(candidate)
+}
+
+test('an explicit binary.path wins over everything', async () => {
+  const explicit = join('C:', 'tools', exe)
+  const found = await resolveBinary({
+    config: config({ binary: { path: explicit } }),
+    dataDir,
+    packageRoot,
+    exists: only(explicit, bundled),
+  })
+  assert.deepEqual(found, { path: explicit, source: 'config' })
+})
+
+test('a plugin-shipped bin/xray is preferred over the managed directory', async () => {
+  const found = await resolveBinary({
+    config: config(),
+    dataDir,
+    packageRoot,
+    exists: only(bundled, managed),
+  })
+  assert.deepEqual(found, { path: bundled, source: 'bundled' })
+})
+
+test('the managed data directory is used when the bundle ships nothing', async () => {
+  const found = await resolveBinary({
+    config: config(),
+    dataDir,
+    packageRoot,
+    exists: only(managed),
+  })
+  assert.deepEqual(found, { path: managed, source: 'managed' })
+})
+
+test('DSH_XRAY_BIN is used when no explicit path is configured', async () => {
+  const previous = process.env.DSH_XRAY_BIN
+  process.env.DSH_XRAY_BIN = join('C:', 'portable', exe)
+  try {
+    const found = await resolveBinary({
+      config: config(),
+      dataDir,
+      packageRoot,
+      exists: only(process.env.DSH_XRAY_BIN, bundled),
+    })
+    assert.equal(found.source, 'env')
+  } finally {
+    if (previous === undefined) delete process.env.DSH_XRAY_BIN
+    else process.env.DSH_XRAY_BIN = previous
+  }
+})
+
+test('PATH is the last resort and uses resolveExecutable when available', async () => {
+  const found = await resolveBinary({
+    config: config(),
+    dataDir,
+    packageRoot,
+    exists: () => false,
+    launcher: { resolveExecutable: async () => '/usr/local/bin/xray' },
+  })
+  assert.deepEqual(found, { path: '/usr/local/bin/xray', source: 'path' })
+})
+
+test('a missing binary fails with every candidate listed', async () => {
+  const previousPath = process.env.PATH
+  process.env.PATH = ''
+  try {
+    await assert.rejects(
+      () =>
+        resolveBinary({
+          config: config(),
+          dataDir,
+          packageRoot,
+          exists: () => false,
+          launcher: {},
+        }),
+      (error) => {
+        assert.ok(error instanceof BinaryError)
+        assert.equal(error.code, 'binary-missing')
+        assert.ok(error.candidates.includes(bundled))
+        return true
+      },
+    )
+  } finally {
+    process.env.PATH = previousPath
+  }
+})

package/test/config.test.js

@@ -0,0 +1,106 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { normalizeConfig } from '../lib/config.js'
+
+function base(overrides = {}) {
+  return normalizeConfig({
+    enabled: true,
+    server: {
+      address: 'example.com',
+      port: 443,
+      uuid: '11111111-2222-4333-8444-555555555555',
+      serverName: 'www.example.com',
+      password: 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
+      shortId: 'ab12',
+      ...overrides.server,
+    },
+    ...overrides.root,
+  })
+}
+
+test('a complete REALITY config validates', () => {
+  const { errors } = base()
+  assert.deepEqual(errors, [])
+})
+
+test('missing server address / uuid are field-level errors, not throws', () => {
+  const { config, errors } = normalizeConfig({ enabled: true })
+  assert.equal(config.server.port, 443)
+  assert.ok(errors.some((error) => error.field === 'server.address'))
+  assert.ok(errors.some((error) => error.field === 'server.uuid'))
+})
+
+test('flow requires raw/tcp plus reality/tls', () => {
+  const { errors } = base({ server: { security: 'none', flow: 'xtls-rprx-vision' } })
+  assert.ok(errors.some((error) => error.field === 'server.flow'))
+})
+
+test('an unknown flow value is rejected', () => {
+  const { errors } = base({ server: { flow: 'xtls-rprx-direct' } })
+  assert.ok(errors.some((error) => error.field === 'server.flow'))
+})
+
+test('odd-length shortId is rejected', () => {
+  const { errors } = base({ server: { shortId: 'abc' } })
+  assert.ok(errors.some((error) => error.field === 'server.shortId'))
+})
+
+test('a non-base64url REALITY key is rejected', () => {
+  const { errors } = base({ server: { password: 'not-a-key' } })
+  assert.ok(errors.some((error) => error.field === 'server.password'))
+})
+
+test('legacy publicKey alone is accepted and normalized', () => {
+  const { config, errors } = base({
+    server: {
+      password: '',
+      publicKey: 'BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB',
+    },
+  })
+  assert.deepEqual(errors, [])
+  assert.equal(config.server.password, '')
+  assert.equal(config.server.publicKey, 'BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB')
+})
+
+test('a non-loopback inbound host is rejected', () => {
+  const { errors } = normalizeConfig({ enabled: true, inbound: { host: '0.0.0.0' } })
+  assert.ok(errors.some((error) => error.field === 'inbound.host'))
+})
+
+test('socks inbound may not reuse the http port', () => {
+  const { errors } = base({ root: { inbound: { port: 20808, socks: { enabled: true, port: 20808 } } } })
+  assert.ok(errors.some((error) => error.field === 'inbound.socks.port'))
+})
+
+test('takeover accepts only auto/force/off', () => {
+  const { errors } = base({ root: { takeover: 'always' } })
+  assert.ok(errors.some((error) => error.field === 'takeover'))
+})
+
+test('numbers given as strings are coerced, invalid numbers are errors', () => {
+  const ok = normalizeConfig({ enabled: true, server: { port: '8443' }, inbound: { port: '20999' } })
+  assert.equal(ok.config.server.port, 8443)
+  assert.equal(ok.config.inbound.port, 20999)
+
+  const bad = normalizeConfig({ enabled: true, server: { port: 'abc' } })
+  assert.ok(bad.errors.some((error) => error.field === 'server.port'))
+})
+
+test('disabled rows still normalize', () => {
+  const { config, errors } = normalizeConfig({ enabled: false })
+  assert.equal(config.enabled, false)
+  assert.equal(config.server.flow, 'xtls-rprx-vision')
+  assert.ok(errors.length > 0) // server fields are empty; supervisor skips them when disabled
+})
+
+test('bypass domains accept a comma string and an array', () => {
+  const fromString = normalizeConfig({ routing: { bypassDomains: 'a.test, b.test' } })
+  assert.deepEqual(fromString.config.routing.bypassDomains, ['a.test', 'b.test'])
+  const fromArray = normalizeConfig({ routing: { bypassDomains: ['c.test'] } })
+  assert.deepEqual(fromArray.config.routing.bypassDomains, ['c.test'])
+})
+
+test('network tcp is normalized to raw', () => {
+  const { config } = base({ server: { network: 'tcp' } })
+  assert.equal(config.server.network, 'raw')
+})

package/test/control.test.js

@@ -0,0 +1,166 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import http2 from 'node:http2'
+import {
+  decodeBalancerInfo,
+  decodeQueryStats,
+  encodeGetBalancerInfo,
+  encodeMessageField,
+  encodeOverrideBalancer,
+  encodeQueryStats,
+  encodeStringField,
+  encodeVarint,
+} from '../lib/control/protobuf.js'
+import { GrpcError, grpcUnary } from '../lib/control/grpc.js'
+import { ControlClient } from '../lib/control/client.js'
+
+function frame(payload) {
+  const prefix = Buffer.alloc(5)
+  prefix.writeUInt8(0, 0)
+  prefix.writeUInt32BE(payload.length, 1)
+  return Buffer.concat([prefix, payload])
+}
+
+function statBytes(name, value) {
+  return Buffer.concat([encodeStringField(1, name), Buffer.concat([encodeVarint((2 << 3) | 0), encodeVarint(value)])])
+}
+
+function listen(server) {
+  return new Promise((resolve) => server.listen(0, '127.0.0.1', () => resolve(server.address().port)))
+}
+
+test('varint and string fields use the expected wire bytes', () => {
+  assert.deepEqual([...encodeVarint(0)], [0])
+  assert.deepEqual([...encodeVarint(300)], [0xac, 0x02])
+  const bytes = encodeOverrideBalancer({ balancerTag: 'active', target: 'proxy-hk' })
+  assert.deepEqual([...bytes], [
+    0x0a, 0x06, ...Buffer.from('active'),
+    0x12, 0x08, ...Buffer.from('proxy-hk'),
+  ])
+})
+
+test('QueryStats request carries repeated patterns and reset', () => {
+  const bytes = encodeQueryStats({ patterns: ['outbound>>>', 'inbound>>>'], reset: true })
+  const expected = Buffer.concat([
+    encodeStringField(1, 'outbound>>>'),
+    encodeStringField(1, 'inbound>>>'),
+    Buffer.from([0x10, 0x01]),
+  ])
+  assert.deepEqual([...bytes], [...expected])
+})
+
+test('QueryStats response decodes name/value pairs', () => {
+  const statA = statBytes('outbound>>>proxy-hk>>>traffic>>>uplink', 1234)
+  const statB = statBytes('outbound>>>proxy-hk>>>traffic>>>downlink', 99)
+  const response = Buffer.concat([encodeMessageField(1, statA), encodeMessageField(1, statB)])
+  assert.deepEqual(decodeQueryStats(response), [
+    { name: 'outbound>>>proxy-hk>>>traffic>>>uplink', value: 1234 },
+    { name: 'outbound>>>proxy-hk>>>traffic>>>downlink', value: 99 },
+  ])
+})
+
+test('balancer info decodes the pinned override target', () => {
+  const overrideInfo = Buffer.concat([encodeStringField(2, 'proxy-hk')])
+  const balancer = encodeMessageField(5, overrideInfo)
+  const response = encodeMessageField(1, balancer)
+  assert.deepEqual(decodeBalancerInfo(response), { overrideTarget: 'proxy-hk', principleTargets: [] })
+})
+
+test('GetBalancerInfo request is a single tag field', () => {
+  assert.deepEqual([...encodeGetBalancerInfo({ tag: 'active' })], [0x0a, 0x06, ...Buffer.from('active')])
+})
+
+async function withMockGrpc(handler, run) {
+  const server = http2.createServer()
+  const requests = []
+  server.on('stream', (stream, headers) => {
+    const chunks = []
+    stream.on('data', (chunk) => chunks.push(chunk))
+    stream.on('end', () => {
+      const body = Buffer.concat(chunks)
+      requests.push({ path: headers[':path'], contentType: headers['content-type'], body })
+      handler(stream, headers, body)
+    })
+  })
+  const port = await listen(server)
+  try {
+    await run({ port, requests })
+  } finally {
+    server.close()
+  }
+}
+
+test('grpcUnary speaks unary gRPC over h2c', async () => {
+  const payload = Buffer.concat([encodeStringField(2, 'proxy-hk')])
+  const wrapper = encodeMessageField(1, encodeMessageField(5, payload))
+  await withMockGrpc(
+    (stream) => {
+      stream.respond({ ':status': 200, 'content-type': 'application/grpc', 'grpc-status': '0' })
+      stream.end(frame(wrapper))
+    },
+    async ({ port, requests }) => {
+      const request = Buffer.from([0x0a, 0x06, ...Buffer.from('active')])
+      const response = await grpcUnary({
+        port,
+        path: '/xray.app.router.command.RoutingService/GetBalancerInfo',
+        message: request,
+        timeoutMs: 2000,
+      })
+      assert.deepEqual([...response], [...wrapper])
+      assert.equal(requests.length, 1)
+      assert.equal(requests[0].contentType, 'application/grpc')
+      assert.equal(requests[0].body.readUInt32BE(1), request.length)
+    },
+  )
+})
+
+test('grpcUnary surfaces a non-zero grpc-status as GrpcError', async () => {
+  await withMockGrpc(
+    (stream) => {
+      stream.respond({ ':status': 200, 'content-type': 'application/grpc', 'grpc-status': '5', 'grpc-message': 'boom' })
+      stream.end()
+    },
+    async ({ port }) => {
+      await assert.rejects(
+        () => grpcUnary({ port, path: '/x/y', message: Buffer.alloc(0), timeoutMs: 2000 }),
+        (error) => error instanceof GrpcError && error.code === '5' && /boom/.test(error.message),
+      )
+    },
+  )
+})
+
+test('a connection refusal becomes a readable control error', async () => {
+  const client = new ControlClient({ port: 1, timeoutMs: 300 })
+  await assert.rejects(() => client.getBalancerInfo())
+  const snapshot = client.snapshot()
+  assert.equal(snapshot.reachable, false)
+  assert.match(snapshot.lastError, /ECONNREFUSED|UNAVAILABLE|ECONNRESET/)
+})
+
+test('ControlClient switches the balancer and reads stats', async () => {
+  const statsBody = Buffer.concat([
+    encodeMessageField(1, statBytes('outbound>>>proxy-hk>>>traffic>>>uplink', 42)),
+  ])
+  await withMockGrpc(
+    (stream, headers) => {
+      if (headers[':path'].endsWith('/OverrideBalancerTarget')) {
+        stream.respond({ ':status': 200, 'content-type': 'application/grpc', 'grpc-status': '0' })
+        stream.end(frame(Buffer.alloc(0)))
+      } else if (headers[':path'].endsWith('/QueryStats')) {
+        stream.respond({ ':status': 200, 'content-type': 'application/grpc', 'grpc-status': '0' })
+        stream.end(frame(statsBody))
+      } else {
+        stream.respond({ ':status': 200, 'content-type': 'application/grpc', 'grpc-status': '12' })
+        stream.end()
+      }
+    },
+    async ({ port }) => {
+      const client = new ControlClient({ port, timeoutMs: 2000, balancerTag: 'active' })
+      assert.equal(await client.overrideBalancerTarget('proxy-hk'), 'proxy-hk')
+      assert.equal(client.snapshot().activeTarget, 'proxy-hk')
+      assert.equal(client.snapshot().reachable, true)
+      const stats = await client.queryStats({ patterns: ['outbound>>>'] })
+      assert.deepEqual(stats, [{ name: 'outbound>>>proxy-hk>>>traffic>>>uplink', value: 42 }])
+    },
+  )
+})

package/test/health.test.js

@@ -0,0 +1,75 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import http from 'node:http'
+import { tcpConnect, waitForPort, portIsFree, httpProxyProbe, cancellableDelay } from '../lib/health.js'
+
+function listen(server) {
+  return new Promise((resolve) => server.listen(0, '127.0.0.1', () => resolve(server.address().port)))
+}
+
+test('tcpConnect sees a live listener and rejects a dead port', async () => {
+  const server = http.createServer((_req, res) => res.end())
+  const port = await listen(server)
+  try {
+    assert.equal(await tcpConnect('127.0.0.1', port, 500), true)
+    assert.equal(await tcpConnect('127.0.0.1', port + 1, 300), false)
+  } finally {
+    server.close()
+  }
+})
+
+test('waitForPort polls until a late listener appears', async () => {
+  const port = 21000 + Math.floor(Math.random() * 500)
+  const succeeded = waitForPort({ host: '127.0.0.1', port, timeoutMs: 2000, intervalMs: 25 })
+  let server
+  setTimeout(() => {
+    server = http.createServer((_req, res) => res.end())
+    server.listen(port, '127.0.0.1')
+  }, 150)
+  assert.equal(await succeeded, true)
+  server.close()
+})
+
+test('waitForPort gives up inside the budget', async () => {
+  const port = 21500 + Math.floor(Math.random() * 500)
+  const started = Date.now()
+  assert.equal(await waitForPort({ host: '127.0.0.1', port, timeoutMs: 300, intervalMs: 25 }), false)
+  assert.ok(Date.now() - started < 1500)
+})
+
+test('portIsFree reflects an occupied port', async () => {
+  const server = http.createServer((_req, res) => res.end())
+  const port = await listen(server)
+  try {
+    assert.equal(await portIsFree('127.0.0.1', port), false)
+  } finally {
+    server.close()
+    await new Promise((resolve) => server.once('close', resolve))
+  }
+  assert.equal(await portIsFree('127.0.0.1', port), true)
+})
+
+test('the functional probe needs a 2xx/3xx answer', async () => {
+  const server = http.createServer((req, res) => {
+    res.statusCode = req.url?.includes('ok') ? 204 : 500
+    res.end()
+  })
+  const port = await listen(server)
+  try {
+    const good = await httpProxyProbe({ host: '127.0.0.1', port, url: 'http://probe.test/ok', timeoutMs: 1000 })
+    assert.deepEqual(good, { ok: true, status: 204 })
+    const bad = await httpProxyProbe({ host: '127.0.0.1', port, url: 'http://probe.test/fail', timeoutMs: 1000 })
+    assert.equal(bad.ok, false)
+    assert.equal(bad.status, 500)
+  } finally {
+    server.close()
+  }
+})
+
+test('cancellableDelay returns early on abort', async () => {
+  const controller = new AbortController()
+  const started = Date.now()
+  setTimeout(() => controller.abort(), 20)
+  await cancellableDelay(5000, controller.signal)
+  assert.ok(Date.now() - started < 1000)
+})

package/test/index.test.js

@@ -0,0 +1,52 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { apply, name } from '../index.js'
+
+const silent = { info() {}, warn() {}, error() {}, debug() {} }
+
+function fakeCtx() {
+  const effects = []
+  return {
+    logger: silent,
+    effects,
+    effect(callback, label) {
+      const disposer = callback()
+      effects.push({ label, disposer })
+      return () => disposer?.()
+    },
+  }
+}
+
+test('the plugin exports the documented entry shape', () => {
+  assert.equal(name, 'dsh-2xray')
+  assert.equal(typeof apply, 'function')
+})
+
+test('a disabled row registers cleanup and never spawns', async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'dsh-xray-index-'))
+  try {
+    const ctx = fakeCtx()
+    const dispose = apply(ctx, { enabled: false, binary: { dataDir: dir } })
+    assert.equal(typeof dispose, 'function')
+    assert.equal(ctx.effects.length, 1)
+    await new Promise((resolve) => setTimeout(resolve, 30))
+    await dispose()
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test('an incomplete config does not throw from apply', async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'dsh-xray-index-'))
+  try {
+    const ctx = fakeCtx()
+    const dispose = apply(ctx, { enabled: true, binary: { dataDir: dir } })
+    await new Promise((resolve) => setTimeout(resolve, 50))
+    await dispose()
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})

package/test/multi-node.test.js

@@ -0,0 +1,111 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { normalizeConfig } from '../lib/config.js'
+import { buildXrayConfig } from '../lib/xray-config.js'
+
+function node(id, overrides = {}) {
+  return {
+    id,
+    address: `${id}.example.com`,
+    port: 443,
+    uuid: '11111111-2222-4333-8444-555555555555',
+    serverName: 'www.example.com',
+    password: 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
+    shortId: 'ab12',
+    ...overrides,
+  }
+}
+
+function multi(overrides = {}) {
+  return normalizeConfig({
+    enabled: true,
+    nodes: [node('hk-01'), node('jp-01')],
+    control: { enabled: true, port: 10085 },
+    ...overrides,
+  })
+}
+
+test('multiple nodes get distinct outbound tags and default to the first', () => {
+  const { config, errors } = multi()
+  assert.deepEqual(errors, [])
+  assert.deepEqual(config.nodes.map((entry) => entry.tag), ['proxy-hk-01', 'proxy-jp-01'])
+  assert.equal(config.activeNode, 'proxy-hk-01')
+})
+
+test('activeNode may name an id or a tag', () => {
+  assert.equal(multi({ activeNode: 'jp-01' }).config.activeNode, 'proxy-jp-01')
+  assert.equal(multi({ activeNode: 'proxy-jp-01' }).config.activeNode, 'proxy-jp-01')
+})
+
+test('an unknown activeNode falls back to the first node with a warning', () => {
+  const { config, warnings } = multi({ activeNode: 'nope' })
+  assert.equal(config.activeNode, 'proxy-hk-01')
+  assert.ok(warnings.some((warning) => warning.includes('activeNode')))
+})
+
+test('duplicate outbound tags are rejected', () => {
+  const { errors } = multi({ nodes: [node('a', { tag: 'same' }), node('b', { tag: 'same' })] })
+  assert.ok(errors.some((error) => /tag 重复/.test(error.message)))
+})
+
+test('the control port may not collide with an inbound port', () => {
+  const { errors } = multi({ control: { enabled: true, port: 20808 } })
+  assert.ok(errors.some((error) => error.field === 'control.port'))
+})
+
+test('control host must be loopback', () => {
+  const { errors } = multi({ control: { enabled: true, host: '0.0.0.0' } })
+  assert.ok(errors.some((error) => error.field === 'control.host'))
+})
+
+test('multiple nodes without the control plane warn loudly', () => {
+  const { warnings } = multi({ control: { enabled: false } })
+  assert.ok(warnings.some((warning) => warning.includes('control.enabled')))
+})
+
+test('multi-node config preloads every outbound plus one balancer', () => {
+  const { config } = multi()
+  const built = buildXrayConfig(config)
+  assert.deepEqual(
+    built.outbounds.map((outbound) => outbound.tag),
+    ['proxy-hk-01', 'proxy-jp-01', 'direct', 'block'],
+  )
+  assert.deepEqual(built.routing.balancers, [
+    {
+      tag: 'active',
+      selector: ['^proxy-hk-01$', '^proxy-jp-01$'],
+      strategy: { type: 'random' },
+    },
+  ])
+  const catchAll = built.routing.rules.at(-1)
+  assert.equal(catchAll.balancerTag, 'active')
+  assert.equal(catchAll.outboundTag, undefined)
+})
+
+test('the control plane adds the api inbound, service list, stats and routing rule', () => {
+  const { config } = multi()
+  const built = buildXrayConfig(config)
+  const apiInbound = built.inbounds.find((inbound) => inbound.tag === 'api')
+  assert.equal(apiInbound.protocol, 'dokodemo-door')
+  assert.equal(apiInbound.listen, '127.0.0.1')
+  assert.equal(apiInbound.port, 10085)
+  assert.deepEqual(built.api, {
+    tag: 'api',
+    services: ['HandlerService', 'StatsService', 'RoutingService'],
+  })
+  assert.deepEqual(built.stats, {})
+  assert.equal(built.policy.system.statsOutboundUplink, true)
+  assert.deepEqual(built.routing.rules[0], { type: 'field', inboundTag: ['api'], outboundTag: 'api' })
+})
+
+test('a single node keeps the legacy config shape (no balancer, api or stats)', () => {
+  const { config } = normalizeConfig({
+    enabled: true,
+    server: node('solo'),
+  })
+  const built = buildXrayConfig(config)
+  assert.equal(built.routing.balancers, undefined)
+  assert.equal(built.api, undefined)
+  assert.equal(built.stats, undefined)
+  assert.equal(built.routing.rules.at(-1).outboundTag, 'proxy')
+})