Peers

When someone running the same protocol comes online, you get a peer. Send them data and pin connections you care about.

Sending data

peer.send (peer: Peer, payload: Buffer): bool

Send a payload to a peer. The typed wrapper app.peer.send(peer, frame) adds automatic retry on buffer-full (up to 15 seconds).

await app.peer.send(peer, Buffer.from('hello'));

Frames are raw bytes — you choose the encoding. Most apps use CBOR:

import { encodeOne, decodeFirstSync } from 'cbor';

await app.peer.send(peer, encodeOne({ type: 'chat', text: 'hello' }));

app.on('frame', (peer, data) => {
    const msg = decodeFirstSync(data);
    console.log(peer.toString(), msg.text);
});

Peer pins

By default, connections are opportunistic — wish-core connects when it discovers a peer and disconnects when idle. Pins let you declare which connections matter to your app.

peer.pin (luid: Uid, ruid: Uid, rhid: Hid, policy: string, priority?: int): bool

Pin a peer — tell wish-core to maintain this connection.

const ANY_HOST = Buffer.alloc(32); // all zeros = any host

await app.peer.pin(myUid, bobUid, ANY_HOST, 'eager', 0);

Policies:

• 'always' — maintain connection persistently, reconnect on failure
• 'eager' — connect when possible, allow disconnect when idle

Priority: 0 = highest, 255 = lowest. When resources are limited, higher priority pins are maintained first.

peer.unpin (luid: Uid, ruid: Uid, rhid: Hid): bool

Remove a peer pin.

peer.pins (void): Pin[]

List this app's peer pins.

const pins = await app.peer.pins();

for (const pin of pins) {
    console.log(pin.policy, pin.priority);
}