Peers

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

Peers vs. connections

These are two different layers, and the distinction matters when you build UI around presence:

• A connection is a transport-level encrypted link between two hosts (devices). There is one connection per (luid, ruid, rhid), and it is shared by every app talking to that host. Connections are wish-core's concern — your app never opens or sees them directly.
• A peer is an app-level relationship: the tuple (luid, ruid, rhid, rsid, protocol). A peer exists only when all three hold:
  1. the two hosts have a connection,
  2. both sides run the same protocol, and
  3. the local app is permitted to use luid on that connection.

So a host can be connected without any peer being online for your app — the device is reachable, but nothing is speaking your protocol there. Presence in an app should track peers, not connections: a peer going online is the signal that there is something at the other end you can actually talk to.

You learn about peers through the online/offline events — your app receives online when a peer appears and offline when it goes away.

Sending data

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

Send a payload to a peer. No built-in retry — a full send buffer fails the call immediately (507); resending is your app's decision (drop, queue, or back off).

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);
}