# @holesail/hyper-cmd-lib-net

> Network library to pipe local and hypderdht udp/tcp streams

Latest version **2.0.1** (published 2026-09-01) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @holesail/hyper-cmd-lib-net
pnpm add @holesail/hyper-cmd-lib-net
yarn add @holesail/hyper-cmd-lib-net
bun add @holesail/hyper-cmd-lib-net
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 2.0.1 |
| Published | 2026-09-01 |
| First published | 2024-04-14 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 48.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | supersuryaansh |
| Maintainers | supersuryaansh |

## Links

- npm: https://www.npmjs.com/package/@holesail/hyper-cmd-lib-net
- Repository: https://github.com/holesail/hyper-cmd-lib-net
- Homepage: https://github.com/holesail/hyper-cmd-lib-net/
- Issues: https://github.com/holesail/hyper-cmd-lib-net/issues
- npm.io page: https://npm.io/package/@holesail/hyper-cmd-lib-net

## Dependencies (5)

- [net](https://npm.io/package/net.md) npm:bare-net@^2.3.3
- [dgram](https://npm.io/package/dgram.md) npm:bare-dgram@^1.1.1
- [bare-net](https://npm.io/package/bare-net.md) ^2.3.3
- [bare-tcp](https://npm.io/package/bare-tcp.md) ^2.6.1
- [bare-dgram](https://npm.io/package/bare-dgram.md) ^1.1.1

## Recent versions

- 2.0.1 (latest) — 2026-09-01
- 2.0.0 — 2026-08-04
- 1.1.2 — 2025-10-26
- 1.1.1 — 2025-10-26
- 1.1.0 — 2025-10-26
- 1.0.0 — 2025-10-25
- 0.4.0 — 2025-08-07
- 0.3.0 — 2025-05-25
- 0.2.1 — 2024-12-20
- 0.2.0 — 2024-12-15
- 0.1.1 — 2024-09-15
- 0.1.0 — 2024-04-14

## README

# hyper-cmd-lib-net

Pipe local and remote (hyperdht) TCP/UDP streams together.

```
npm i @holesail/hyper-cmd-lib-net
```

## Usage

```js
const { createTcpProxy } = require('@holesail/hyper-cmd-lib-net')

const proxy = createTcpProxy(
  () => tunnel.createStream(),
  { port: 8080, host: '127.0.0.1' },
  () => console.log('listening on', proxy.address())
)
```

## API

#### `connPiper(a, bFactory, [opts])`

Pipe two duplex streams together, and destroy both the moment either one closes or
errors.

`bFactory()` is called once to make the second stream. Throw, or return `null`, to
reject the connection — `a` gets destroyed and `bFactory` is never called again.

```js
connPiper(a, () => b, {
  logger: null, // { debug, info, warn, error }, defaults to a no-op logger
  onDestroy: (err) => {} // called once, when the pipe is torn down
})
```

#### `const proxy = createTcpProxy(remoteTunnel, opts, onListen)`

Start a TCP server. Every accepted connection is piped to a fresh `remoteTunnel()`
stream using `connPiper` above.

```js
createTcpProxy(
  () => tunnel.createStream(),
  {
    port: 0,
    host: '127.0.0.1',
    logger: null,
    onDestroy: (err) => {}
  },
  () => {}
)
```

Returns the underlying `net.Server`. `proxy.close()` also destroys any connections
still open, so it doesn't need `'close'` listeners on every socket to fully shut down.

#### `pipeTcpServer(remoteStream, leftover, opts)`

The other direction of `createTcpProxy` — connects out to a local TCP service and pipes
it to `remoteStream`.

```js
pipeTcpServer(remoteStream, leftoverBuffer, {
  port: 3000,
  host: '127.0.0.1'
})
```

`leftover` is a buffer of bytes already read off `remoteStream` (eg while sniffing a
protocol) that gets written to the local socket before piping starts. Pass `null` if
there isn't any.

#### UDP framing

UDP has no stream boundaries, so the two helpers below speak a small length-prefixed
framing over the tunnel instead: 4 bytes big-endian length, then that many bytes of
payload. They're meant to be run as a pair, one on each end of a tunnel.

#### `const { proxySocket, clients } = createUdpFramedProxy(createTunnel, opts, onBind)`

Bind a UDP socket. Every distinct sender (by `address:port`) gets its own tunnel
stream, made lazily via `createTunnel()` on its first packet.

```js
createUdpFramedProxy(
  () => tunnel.createStream(),
  {
    port: 0,
    host: '127.0.0.1',
    maxFrameSize: 65535,
    logger: null
  },
  () => {}
)
```

`clients` is a `Map` of `address:port` -> `{ stream, rinfo, buffer }`. A frame bigger
than `maxFrameSize` destroys that client's tunnel and evicts it — the next packet from
the same client just starts a new one.

#### `pipeUdpFramedServer(stream, leftover, opts)`

The other end of the pair. Unframes packets off `stream` and forwards them as plain
UDP to a local service, framing replies back onto `stream`.

```js
pipeUdpFramedServer(remoteStream, leftoverBuffer, {
  port: 53,
  host: '127.0.0.1',
  maxFrameSize: 65535
})
```

A clean `end` on `stream` ends the local socket, no drama. An `error`, or a frame over
`maxFrameSize`, destroys it.

## License

Apache-2.0

---
_Source: https://npm.io/package/@holesail/hyper-cmd-lib-net · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._