Skip to content

Commit

Permalink
Some small changes:
Browse files Browse the repository at this point in the history 
 - Add link to "Use Cases" in EXPLAINER.md
 - Adjust the order of paragraphs to make them unified
 - Remove "Examples" chapter temporarily: there are two examples, one is moved
   to the corresponding chapter, the other one was removed due to duplication.
   Maybe we can add the actual use cases based on this API in the future.
 - Fix some errors.
  • Loading branch information
@wangw-1991
wangw-1991 committed Dec 28, 2023
1 parent 1ce345b commit 6e13b13
Showing 1 changed file with 99 additions and 134 deletions.
233 changes: 99 additions & 134 deletions index.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ The Local Peer-to-Peer API aims to give browsers the means to communicate direct

Many modern Web security measures rely on the presence of naming, signaling and certificate authorities. Local use-cases where these authorities are not readily available have started lagging behind in user experience or are not supported altogether. The Local Peer-to-Peer API aims to bring back first-class support for local communication use-cases while working within the same strict user-friendliness, security and privacy requirements.

Examples of potential uses of this API include: Collaboration tools that work during an internet outage or emergency situations, connecting to your NAS, your home security system, your robotic assistant doing the dishes or your GPU farm in the basement that's running your personalized virtual assistant.
Examples of potential uses of this API include: Collaboration tools that work during an internet outage or emergency situations, connecting to your NAS, your home security system, your robotic assistant doing the dishes or your GPU farm in the basement that's running your personalized virtual assistant. See also [Use Cases](https://github.com/WICG/local-peer-to-peer/blob/main/EXPLAINER.md#use-cases).

This specification aims to strike a balance between creating a powerful new building block for developers and providing a seamless, secure and privacy preserving experience for browser users. As an example: while the API doesn't provide raw socket access, it does aim to give developers the flexibility to innovate on top by providing a persistent, two-way communication channel with little overhead.

Expand Down Expand Up @@ -222,11 +222,11 @@ The capabilities of the Local WebTransport session are defined in [[!webtranspor

Note: The WebTransport-over-QUIC protocol is yet to be defined. Potentially considering earlier work such as [draft-vvv-webtransport-quic](https://datatracker.ietf.org/doc/html/draft-vvv-webtransport-quic-02).

<section algorithm="LP2PReceiver">

LP2PReceiver Interface {#lp2p-receiver}
================================================

<section algorithm="LP2PReceiver">

The <dfn interface>LP2PReceiver</dfn> interface allows advertising on the local network, enabling other peers to discover and connect.

<pre class="idl">
Expand Down Expand Up @@ -265,25 +265,6 @@ dictionary LP2PConnectionEventInit : EventInit {
};
</pre>

Examples {#lp2p-receiver-examples}
---------------------------------

Example: Setting up a receiver to listen for connections:


<pre class='example' highlight='js'>
const receiver = new LP2PReceiver({
nickname: "example-receiver",
});
receiver.onconnection = e => {
console.log("Connection established!");
const conn = e.connection;
};

// Blocks until permission is received.
await receiver.start();
</pre>

Events {#lp2p-receiver-events}
------------------------------

Expand Down Expand Up @@ -326,6 +307,24 @@ The following are the <a>event handlers</a> (and their corresponding <a>event ha
</tbody>
</table>

Examples {#lp2p-receiver-examples}
---------------------------------

Example: Setting up a receiver to listen for connections:

<pre class='example' highlight='js'>
const receiver = new LP2PReceiver({
nickname: "example-receiver",
});
receiver.onconnection = e => {
console.log("Connection established!");
const conn = e.connection;
};

// Blocks until permission is received.
await receiver.start();
</pre>

</section>

<section algorithm="LP2PRequest">
Expand Down Expand Up @@ -358,7 +357,6 @@ Examples {#lp2p-request-examples}

Example: Setting up a request for a connection:


<pre class='example' highlight='js'>
const request = new LP2PRequest({
nickname: "example-request",
Expand All @@ -384,10 +382,6 @@ interface LP2PConnection : EventTarget {
};
</pre>

</section>

<section algorithm="LP2PDataChannel">

LP2PQuicTransport Interface Extensions {#lp2p-connection-quic-transport-extensions}
-------------------------------------------------------------------

Expand Down Expand Up @@ -439,11 +433,14 @@ const transport = new LP2PQuicTransport(conn);
await transport.ready;
</pre>

</section>

<section algorithm="LP2PDataChannel">

The LP2PDataChannel Interface {#lp2p-data-channel}
==========================================

The LP2PDataChannel interface represents a bi-directional data channel between two peers. An LP2PDataChannel is created via a [factory method](#lp2p-data-channel-extensions) on a LP2PConnection object.
The LP2PDataChannel interface represents a bi-directional data channel between two peers. An LP2PDataChannel is created via a [factory method](#lp2p-connection-data-channel-extensions) on a LP2PConnection object.

Note: The LP2PDataChannel interface is purposefully kept as close as possible to the [RTCDataChannel](https://www.w3.org/TR/webrtc/#rtcdatachannel) interface defined in [[!webrtc]]. The aim is to allow seamless transition of developers that are familiar with WebRTC as well as allowing libraries to easily work with both the [[!webrtc]] and LP2P API.

Expand Down Expand Up @@ -477,7 +474,6 @@ dictionary LP2PDataChannelInit {
};
</pre>


Events {#lp2p-data-channel-events}
---------------------------------

Expand Down Expand Up @@ -520,10 +516,10 @@ The following event is [=fire an event|fired=] at the {{LP2PDataChannel}} object
</tbody>
</table>

Data Channel Event handlers {#lp2p-data-channel-event-handlers}
Event handlers {#lp2p-data-channel-event-handlers}
---------------------------------------------------------------

The following are the <a>event handlers</a> (and their corresponding <a>event handler event types</a>) that must be supported, as <a>event handler IDL attributes</a>, by all objects implementing the [[#lp2p-connection|LP2PConnection]] interface:
The following are the <a>event handlers</a> (and their corresponding <a>event handler event types</a>) that must be supported, as <a>event handler IDL attributes</a>, by all objects implementing the [[#lp2p-data-channel|LP2PDataChannel]] interface:

<table class="data">
<thead>
Expand Down Expand Up @@ -555,7 +551,7 @@ The following are the <a>event handlers</a> (and their corresponding <a>event ha
</tr>
</table>

LP2PConnection Interface Extensions {#lp2p-data-channel-extensions}
LP2PConnection Interface Extensions {#lp2p-connection-data-channel-extensions}
-------------------------------------------------------------------

<pre class="idl">
Expand Down Expand Up @@ -584,7 +580,7 @@ dictionary LP2PDataChannelEventInit : EventInit {
};
</pre>

Extensions Events {#lp2p-data-channel-extensions-events}
Extensions Events {#lp2p-connection-data-channel-extensions-events}
------------------------------

The following event is [=fire an event|fired=] at the {{LP2PConnection}} object:
Expand All @@ -606,7 +602,7 @@ The following event is [=fire an event|fired=] at the {{LP2PConnection}} object:
</tbody>
</table>

Extensions Event handlers {#lp2p-data-channel-extensions-event-handlers}
Extensions Event handlers {#lp2p-connection-data-channel-extensions-event-handlers}
------------------------------------------------------------------------

The following are the <a>event handlers</a> (and their corresponding <a>event handler event types</a>) that must be supported, as <a>event handler IDL attributes</a>, by all objects implementing the {{LP2PConnection}} interface:
Expand All @@ -626,6 +622,57 @@ The following are the <a>event handlers</a> (and their corresponding <a>event ha
</tbody>
</table>

Examples {#data-channel-communication-examples}
---------------------------------------------------

Example: Receive a {{LP2PDataChannel}} on an existing connection as receiver:

<pre class='example' highlight='js'>
const receiver = new LP2PReceiver({
nickname: "example-receiver",
});

receiver.onconnection = e => {
const conn = e.connection;
console.log("Receiver: Got a connection!");

conn.ondatachannel = e => {
const channel = e.channel;

channel.onmessage = e => {
const message = e.data;
console.log(\`Receiver: Received message: ${message}\`);
};

channel.send("Good day to you, requester!");
};
};

await receiver.start();
</pre>

Example: Create a {{LP2PDataChannel}} on an existing connection as requester:

<pre class='example' highlight='js'>
const request = new LP2PRequest({
nickname: "example-request",
});

const conn = await request.start();
console.log("Requester: Got a connection!");

const channel = conn.createDataChannel("My Channel");

channel.onopen = e => {
channel.onmessage = e => {
const message = e.data;
console.log(\`Requester: Received message: ${message}\`);
};

channel.send("Good day to you, receiver!");
};
</pre>

</section>

<section algorithm="LP2PQuicTransport">
Expand Down Expand Up @@ -659,6 +706,23 @@ partial interface LP2PReceiver {
};
</pre>

LP2PQuicTransportEvent {#lp2p-quic-transport-event}
------------------------------------------------

Issue: In general, when defining a new interface that inherits from Event please always ask feedback from the WHATWG or the W3C WebApps WG community. See [defining event interfaces](https://dom.spec.whatwg.org/#defining-event-interfaces).

<pre class="idl">
[Exposed=(Window,Worker), SecureContext]
interface LP2PQuicTransportEvent : Event {
constructor(DOMString type, LP2PQuicTransportEventInit QuicTransportEventInitDict);
readonly attribute LP2PQuicTransport transport;
};

dictionary LP2PQuicTransportEventInit : EventInit {
required LP2PQuicTransport transport;
};
</pre>

Extensions Events {#lp2p-quic-transport-events}
------------------------------

Expand Down Expand Up @@ -701,23 +765,6 @@ The following are the <a>event handlers</a> (and their corresponding <a>event ha
</tbody>
</table>

LP2PQuicTransportEvent {#lp2p-quic-transport-event}
------------------------------------------------

Issue: In general, when defining a new interface that inherits from Event please always ask feedback from the WHATWG or the W3C WebApps WG community. See [defining event interfaces](https://dom.spec.whatwg.org/#defining-event-interfaces).

<pre class="idl">
[Exposed=(Window,Worker), SecureContext]
interface LP2PQuicTransportEvent : Event {
constructor(DOMString type, LP2PQuicTransportEventInit QuicTransportEventInitDict);
readonly attribute LP2PQuicTransport transport;
};

dictionary LP2PQuicTransportEventInit : EventInit {
required LP2PQuicTransport transport;
};
</pre>

Examples {#lp2p-quic-transport-examples}
----------------------------------------

Expand All @@ -741,7 +788,7 @@ const receiver = new LP2PReceiver({
nickname: "example-receiver",
});

receiver.ontransport = e => {
receiver.ontransport = async e => {
const transport = e.transport;

// Blocks until transport is ready.
Expand All @@ -756,88 +803,6 @@ Refer to the [WebTransport examples](https://www.w3.org/TR/webtransport/#example

</section>

Examples {#examples}
====================

Data Channel Communication {#examples-data-channel}
---------------------------------------------------

<pre class='example' highlight='js'>
// Peer A
const receiver = new LP2PReceiver({
nickname: "Peer A",
});

receiver.onconnection = e => {
const conn = e.connection;
console.log("Receiver: Got a connection!");

conn.ondatachannel = e => {
const channel = e.channel;

channel.onmessage = e => {
const message = e.data;
console.log(\`Receiver: Received message: ${message}\`);
};

channel.send("Good day to you, requester!");
};
};

await receiver.start();

// Peer B
const request = new LP2PRequest({
nickname: "Peer B",
});

const conn = await request.start();
console.log("Requester: Got a connection!");

const channel = conn.createDataChannel("My Channel");

channel.onopen = e => {
channel.onmessage = e => {
const message = e.data;
console.log(\`Requester: Received message: ${message}\`);
};

channel.send("Good day to you, receiver!");
};
</pre>

WebTransport Communication {#examples-web-transport}
---------------------------------------------------

<pre class='example' highlight='js'>
// Peer A
const receiver = new LP2PReceiver({
nickname: "Peer A",
});

receiver.ontransport = e => {
const transport = e.transport;

// Blocks until transport is ready.
await transport.ready;
}

// Blocks until permission is received.
await receiver.start();

// Peer B
const request = new LP2PRequest({
nickname: "Peer B",
});

const transport = new LP2PQuicTransport(request);

// Blocks until transport is ready.
await transport.ready;
</pre>

Refer to the [WebTransport examples](https://www.w3.org/TR/webtransport/#examples) for usage of a [[!webtransport]] object.

Appendix A: OSP Extension Messages {#appendix-a}
================================================

Expand Down

0 comments on commit 6e13b13

Please sign in to comment.