@hyperfrontend/network-protocol/browser/packetpacket
Browser-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 /browser/v3 and /browser/v4 protocols convert between the two shapes; /node/packet exports the same code.
API Reference§
ƒ Functions
Creates the base structure for a network packet with origin and target. Validates origin and target URLs before creating the frozen packet base.
Parameters
Returns
PacketBaseA 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-...' }§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
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 } }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
booleanTrue 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')
// => falseValidates 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
booleanTrue if the value is a valid UUID v4 string, false otherwise
Example
Validating packet targets
isValidTarget('6ba7b810-9dad-11d1-80b4-00c04fd430c8')
// => true
isValidTarget('invalid')
// => falseChecks 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
unknownTrue when the value has the shape of an
UnencryptedPacketExample
Validating a packet before sealing
isValidUnencryptedPacket({ origin, target, data: { pid, id, sequence: 1, message: { action: 'ping' }, schema, schemaHash } })
// => trueChecks 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
unknownTrue when the value is a
Uint8Array with at least one byteExample
Validating wire packets
isValidWirePacket(new Uint8Array([1, 2, 3]))
// => true
isValidWirePacket({ data: 'not binary' })
// => false◈ Interfaces
Routing fields every plaintext packet carries
Properties
A packet in the clear: routing fields plus the data envelope
Properties
A packet a pipeline stage rejected and the pipeline discarded
Properties
§
readonly direction:"inbound" | "outbound"Whether the packet was leaving (
outbound) or arriving (inbound)◆ Types
A packet at either end of the pipeline
type Packet = UnencryptedPacket<T> | WirePacketBytes as they travel: a sealed frame carrying one packet
type WirePacket = Uint8ArrayReceives each packet a pipeline discards
type PacketDropHandler = (drop: PacketDrop) => voidThe pipeline stage that rejected a packet
type PacketDropStage = "seal" | "open"Opens wire bytes into a plaintext packet under the session's receiving key
type PacketOpener = (packet: WirePacket) => Promise<UnencryptedPacket<T>>Seals a plaintext packet into wire bytes under the session's sending key
type PacketSealer = (packet: UnencryptedPacket<T>) => Promise<WirePacket>