← Back to @hyperfrontend/network-protocol
@hyperfrontend/network-protocol/node/packet

packet

Node.js-side packet types, builders, and validators.

A packet is either a plaintext UnencryptedPacket<T> (origin, target, and a Data<T> envelope) or the sealed WirePacket bytes that carry it. This entry point exposes createPacketBase and createUnencryptedPacket, the validators isValidOrigin, isValidTarget, isValidUnencryptedPacket, and isValidWirePacket, and the operation and drop types (PacketSealer, PacketOpener, PacketDrop, PacketDropHandler, PacketDropStage) that a session protocol and a channel's onDrop handler share. Origins and targets are UUID v4 strings. The /node/v3 and /node/v4 protocols convert between the two shapes; /browser/packet exports the same code, so packets cross runtime boundaries cleanly.

API Reference§

ƒ Functions

§function

createPacketBase(origin: string, target: string): PacketBase

Creates the base structure for a network packet with origin and target. Validates origin and target URLs before creating the frozen packet base.
Parameters
NameTypeDescription
§origin
stringThe origin URL of the packet sender
§target
stringThe target URL of the packet recipient
Returns
PacketBase
A frozen PacketBase object with validated origin and target
Example

Creating a packet base

const base = createPacketBase(
  '550e8400-e29b-41d4-a716-446655440000',
  '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
)
// => { origin: '550e8400-...', target: '6ba7b810-...' }
View source →
§function

createUnencryptedPacket<T>(origin: string, target: string, data: Data<T>): UnencryptedPacket<T>

Creates an unencrypted network packet with validated origin, target, and data. The packet is frozen to prevent modifications after creation.
Parameters
NameTypeDescription
§origin
stringThe origin URL of the packet sender
§target
stringThe target URL of the packet recipient
§data
Data<T>The data payload to include in the packet
Returns
UnencryptedPacket<T>
A frozen UnencryptedPacket containing the origin, target, and data
Example

Creating an unencrypted packet

const packet = createUnencryptedPacket(originId, targetId, await createData(pid, 1, { action: 'ping' }))
// => { origin, target, data: { pid, id, sequence, message, schema, schemaHash } }
View source →
§function

isValidOrigin(origin: unknown): boolean

Validates whether the provided value is a valid packet origin identifier. The origin must be a 36-character UUID v4 string.
Parameters
NameTypeDescription
§origin
unknownThe value to validate as a packet origin
Returns
boolean
True if the value is a valid UUID v4 string, false otherwise
Example

Validating packet origins

isValidOrigin('550e8400-e29b-41d4-a716-446655440000')
// => true

isValidOrigin('not-a-uuid')
// => false
View source →
§function

isValidTarget(target: unknown): boolean

Validates whether the provided value is a valid packet target identifier. The target must be a 36-character UUID v4 string.
Parameters
NameTypeDescription
§target
unknownThe value to validate as a packet target
Returns
boolean
True if the value is a valid UUID v4 string, false otherwise
Example

Validating packet targets

isValidTarget('6ba7b810-9dad-11d1-80b4-00c04fd430c8')
// => true

isValidTarget('invalid')
// => false
View source →
§function

isValidUnencryptedPacket(packet: unknown): unknown

Checks that a value is a plaintext packet: a valid origin, a valid target, and a valid data envelope.
Parameters
NameTypeDescription
§packet
unknownThe value to check
Returns
unknown
True when the value has the shape of an UnencryptedPacket
Example

Validating a packet before sealing

isValidUnencryptedPacket({ origin, target, data: { pid, id, sequence: 1, message: { action: 'ping' }, schema, schemaHash } })
// => true
View source →
§function

isValidWirePacket(packet: unknown): unknown

Checks that a value is a non-empty byte array, the only shape a wire packet takes.
Parameters
NameTypeDescription
§packet
unknownThe value to check
Returns
unknown
True when the value is a Uint8Array with at least one byte
Example

Validating wire packets

isValidWirePacket(new Uint8Array([1, 2, 3]))
// => true

isValidWirePacket({ data: 'not binary' })
// => false
View source →

◈ Interfaces

§interface

PacketBase

Routing fields every plaintext packet carries
Properties
§readonly origin:stringIdentifies the origin of the packet
§readonly target:stringIdentifies the intended recipient of the packet
View source →
§interface

PacketDrop

A packet a pipeline stage rejected and the pipeline discarded
Properties
§readonly direction:"inbound" | "outbound"Whether the packet was leaving (outbound) or arriving (inbound)
§readonly stage:PacketDropStageThe stage that rejected the packet
§readonly reason:stringWhy the stage rejected it
§readonly cause?:unknownThe error the stage threw, when it threw one
§readonly packet:unknownThe packet as the stage received it
View source →
§interface

UnencryptedPacket

A packet in the clear: routing fields plus the data envelope
Properties
§readonly origin:stringIdentifies the origin of the packet
§readonly target:stringIdentifies the intended recipient of the packet
§readonly data:Data<T>The data envelope
View source →

◆ Types

§type

Packet

A packet at either end of the pipeline
type Packet = UnencryptedPacket<T> | WirePacket
View source →
§type

PacketDropHandler

Receives each packet a pipeline discards
type PacketDropHandler = (drop: PacketDrop) => void
View source →
§type

PacketDropStage

The pipeline stage that rejected a packet
type PacketDropStage = "seal" | "open"
View source →
§type

PacketOpener

Opens wire bytes into a plaintext packet under the session's receiving key
type PacketOpener = (packet: WirePacket) => Promise<UnencryptedPacket<T>>
View source →
§type

PacketSealer

Seals a plaintext packet into wire bytes under the session's sending key
type PacketSealer = (packet: UnencryptedPacket<T>) => Promise<WirePacket>
View source →
§type

WirePacket

Bytes as they travel: a sealed frame carrying one packet
type WirePacket = Uint8Array
View source →