← 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

Name	Type	Description
§origin	`string`	The origin URL of the packet sender
§target	`string`	The 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

Name	Type	Description
§origin	`string`	The origin URL of the packet sender
§target	`string`	The 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

Name	Type	Description
§origin	`unknown`	The 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

Name	Type	Description
§target	`unknown`	The 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

Name	Type	Description
§packet	`unknown`	The 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

Name	Type	Description
§packet	`unknown`	The 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:string

Identifies the origin of the packet

§readonly target:string

Identifies the intended recipient of the packet

View source →

§interface

PacketDrop

A packet a pipeline stage rejected and the pipeline discarded

Properties

§readonly cause?:unknown

The error the stage threw, when it threw one

§readonly direction:"inbound" | "outbound"

Whether the packet was leaving (outbound) or arriving (inbound)

§readonly packet:unknown

The packet as the stage received it

§readonly reason:string

Why the stage rejected it

§readonly stage:PacketDropStage

The stage that rejected the packet

View source →

§interface

UnencryptedPacket

A packet in the clear: routing fields plus the data envelope

Properties

§readonly data:Data<T>

The data envelope

§readonly origin:string

Identifies the origin of the packet

§readonly target:string

Bytes as they travel: a sealed frame carrying one packet

type WirePacket = Uint8Array

View source →