From 9acf39f0ae8320f924f0cc48f6213c708a183cdf Mon Sep 17 00:00:00 2001 From: Alex Andres Date: Sun, 8 Nov 2026 17:02:29 +0100 Subject: [PATCH] feat: add file transfer over data channels --- README.md | 1 + docs/.vitepress/sidebar.ts | 1 + docs/guide/client-api.md | 2 + docs/guide/data/file-transfer.md | 66 + docs/guide/examples.md | 16 + docs/guide/index.md | 1 + .../webrtc/examples/FileTransferExample.java | 125 ++ .../webrtc/client/transfer/FileTransfers.java | 1121 +++++++++++++++++ .../onvoid/webrtc/client/transfer/Frames.java | 300 +++++ .../webrtc/client/transfer/Incoming.java | 50 + .../client/transfer/IncomingTransfer.java | 41 + .../webrtc/client/transfer/Outgoing.java | 58 + .../client/transfer/OutgoingTransfer.java | 26 + .../webrtc/client/transfer/Transfer.java | 88 ++ .../transfer/TransferCancelledException.java | 37 + .../client/transfer/TransferException.java | 69 + .../webrtc/client/transfer/TransferImpl.java | 173 +++ .../webrtc/client/transfer/TransferOffer.java | 210 +++ .../client/transfer/TransferOptions.java | 143 +++ .../client/transfer/TransferProgress.java | 61 + webrtc/src/main/java/module-info.java | 1 + .../webrtc/client/FileTransferTests.java | 69 + .../onvoid/webrtc/client/LoopbackChannel.java | 240 ++++ .../client/transfer/FileTransfersTests.java | 552 ++++++++ 24 files changed, 3451 insertions(+) create mode 100644 docs/guide/data/file-transfer.md create mode 100644 webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/FileTransferExample.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/FileTransfers.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/Frames.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/Incoming.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/IncomingTransfer.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/Outgoing.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/OutgoingTransfer.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/Transfer.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferCancelledException.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferException.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferImpl.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferOffer.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferOptions.java create mode 100644 webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferProgress.java create mode 100644 webrtc/src/test/java/dev/onvoid/webrtc/client/FileTransferTests.java create mode 100644 webrtc/src/test/java/dev/onvoid/webrtc/client/LoopbackChannel.java create mode 100644 webrtc/src/test/java/dev/onvoid/webrtc/client/transfer/FileTransfersTests.java diff --git a/README.md b/README.md index aafde85c9..4191e15c5 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,7 @@ The library provides a comprehensive set of Java classes that map to the WebRTC - **[WHIP and WHEP](https://jrtc.dev/guide/client-api#whip-and-whep)** - Publish to and play from streaming servers - **[Peer connections](https://jrtc.dev/guide/networking/peer-connection-config)** - The full native API, modeled on the W3C JavaScript API - **[Data channels](https://jrtc.dev/guide/data/data-channels)** - Reliable or unreliable peer-to-peer messaging +- **[File transfer](https://jrtc.dev/guide/data/file-transfer)** - Send files over a data channel with progress, a checksum confirmed by the receiver and resume after a reconnect - **[Statistics](https://jrtc.dev/guide/monitoring/rtc-stats)** - Detailed metrics on connection quality **Audio and video** diff --git a/docs/.vitepress/sidebar.ts b/docs/.vitepress/sidebar.ts index 6613c3863..993d38ac5 100644 --- a/docs/.vitepress/sidebar.ts +++ b/docs/.vitepress/sidebar.ts @@ -54,6 +54,7 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] { collapsed: false, items: [ { text: 'Data Channels', link: '/data/data-channels' }, + { text: 'File Transfer', link: '/data/file-transfer' }, ], }, { diff --git a/docs/guide/client-api.md b/docs/guide/client-api.md index 2eef44fdd..8fb3f8a51 100644 --- a/docs/guide/client-api.md +++ b/docs/guide/client-api.md @@ -759,6 +759,8 @@ DataChannel positions = peer.createChannel("positions", ChannelOptions.builder() `negotiatedId(int)` creates a channel both peers set up themselves with the same id, without announcing it; such a channel never shows up in `onChannel`. The [Data Channels](/guide/data/data-channels) guide explains the options in detail. +A completed `send` future means the data was handed to the transport, not that the remote application processed it. To send files, use `FileTransfers` from `dev.onvoid.webrtc.client.transfer`, which adds the receiver's own confirmations, a SHA-256 checksum, progress, cancelling and resume. See the [File Transfer](/guide/data/file-transfer) guide. + ## WHIP and WHEP Media servers and streaming services take streams with the WebRTC HTTP Ingestion Protocol ([WHIP](https://www.rfc-editor.org/rfc/rfc9725)) and hand them out with its egress counterpart, WHEP. Both exchange one offer and one answer over HTTP. `Whip` publishes tracks, and `Whep` receives a stream: diff --git a/docs/guide/data/file-transfer.md b/docs/guide/data/file-transfer.md new file mode 100644 index 000000000..18af21f37 --- /dev/null +++ b/docs/guide/data/file-transfer.md @@ -0,0 +1,66 @@ +# File Transfer + +`dev.onvoid.webrtc.client.transfer` sends files over a [client API](/guide/client-api) data channel. It adds what a plain `send()` doesn't give you: chunking with bounded memory, progress, cancelling, a confirmation from the receiver with a SHA-256 checksum, and resuming after a reconnect. + +```java +FileTransfers files = FileTransfers.over(peer.createChannel("files")); + +OutgoingTransfer upload = files.send(Paths.get("report.pdf")); +upload.onProgress(p -> System.out.printf("%.0f%%%n", 100 * p.fraction())); +upload.whenDone().thenRun(() -> System.out.println("The receiver has it")); + +// On the other side: +peer.onChannel(channel -> { + if (channel.label().equals("files")) { + FileTransfers.over(channel).onOffer(offer -> + offer.accept(downloads.resolve(offer.safeFileName()))); + } +}); +``` + +`FileTransfers` takes over the channel: nothing else may be sent on it. Files go one at a time in each direction, in the order they were sent, and both peers may send at the same time. Each side reads and writes its files and runs its handlers on a thread of its own, not on the peer's event thread. Those handlers must not block. + +## Confirmation, not just handing data to the transport + +The future that `DataChannel.send()` returns completes once the data has been handed to the transport. It tells you nothing about the receiver. The transfer protocol has its own confirmations: + +- The receiver acknowledges the bytes it wrote to its file, a quarter of its window at a time. Progress on both sides counts confirmed bytes. +- The sender never has more than the receiver's window unconfirmed (`TransferOptions.builder().window(bytes)`, 4 MiB by default). A slow disk therefore slows the sender down instead of filling memory. Keep the window below the receiver's `channelReceiveLimit`. +- `whenDone()` completes only once the receiver has checked the SHA-256 of the whole file against the sender's and moved the file into place. + +## Offers + +An offer's `name()` and `size()` come from the remote peer. Don't turn the name into a path as it is, because it may contain `../` or path separators. `safeFileName()` gives you a single file name that stays in the directory you resolve it against. `reject(reason)` makes the sender's transfer fail with that reason, and the sender's next file follows. If an offer arrives before any handler is registered, it waits for the first handler. + +The data goes to `partialFile()` next to the target, and that file replaces the target only after the checksum matched. If more data arrives than the offer announced, or more than the window allows, or the data is out of order, the receiver treats it as a protocol error: the transfer fails and the channel closes. + +## Cancelling and failures + +`cancel()` works on either side. It tells the remote peer, and the receiver deletes its partial file. The other side fails with a `TransferCancelledException`. Every other failure is a `TransferException`, for example a rejected offer, a checksum mismatch, a read or write error, or a protocol error. + +## Resuming after a reconnect + +When the channel closes, or `close()` is called, unfinished transfers fail with an exception whose `isResumable()` is true. The receiver keeps its partial file. Over a new channel, for example of a new peer after the connection has been set up again, the sender resumes the transfer: + +```java +OutgoingTransfer resumed = newFiles.resume(interrupted); +``` + +The offer keeps its id. If the receiver accepts it with the same target, the transfer continues from the end of the partial file, and the checksum still covers the whole file. With `TransferOptions.builder().resumable(false)`, the receiver deletes partial files on every failure and always starts over. An application that won't resume a transfer deletes `partialFile()` itself. + +## Wire format + +Each frame is one binary message, big-endian, and starts with its type and the 16-byte transfer id: + +| Frame | Type | Fields after the id | +|--------|------|-----------------------------------------| +| OFFER | 1 | version (u8, 1), size (u64), name (text) | +| ACCEPT | 2 | offset (u64), window (u32) | +| REJECT | 3 | reason (text) | +| DATA | 4 | offset (u64), payload | +| ACK | 5 | offset (u64) | +| END | 6 | SHA-256 (32 bytes) | +| DONE | 7 | | +| CANCEL | 8 | failed (u8), reason (text) | + +A text is a u16 length followed by at most 1024 bytes of UTF-8. diff --git a/docs/guide/examples.md b/docs/guide/examples.md index 2a236fbf2..a5210e754 100644 --- a/docs/guide/examples.md +++ b/docs/guide/examples.md @@ -22,6 +22,22 @@ This example is the shortest way to see a complete call working, and a starting mvn exec:java -D"exec.mainClass=dev.onvoid.webrtc.examples.ClientApiExample" -D"exec.args=10" ``` +## File Transfer + +The [`FileTransferExample`](https://github.com/devopvoid/webrtc-java/blob/master/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/FileTransferExample.java) connects two peers in one process with the [Client API](/guide/client-api), and sends a file from one to the other with [File Transfer](/guide/data/file-transfer). It needs no audio or video hardware and no server. + +**Key features demonstrated:** +- Running `FileTransfers` over a data channel on both sides +- Accepting an offer under a safe file name, in a directory of the application's choice +- Following the progress the receiver confirms +- Waiting until the receiver checked the SHA-256 of the file and moved it into place + +Pass a file to send, or a size in MiB for a file of random data, 20 by default: + +```bash +mvn exec:java -D"exec.mainClass=dev.onvoid.webrtc.examples.FileTransferExample" -D"exec.args=50" +``` + ## PeerConnection The [`PeerConnectionExample`](https://github.com/devopvoid/webrtc-java/blob/master/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/PeerConnectionExample.java) sends the camera and the microphone from one peer to another in the same process, with the [Client API](/guide/client-api), and logs the video frames and audio that arrive. diff --git a/docs/guide/index.md b/docs/guide/index.md index 0b6912e80..e3c06cfb3 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -27,6 +27,7 @@ This section provides detailed guides for various features of the webrtc-java li ## Data Communication - [Data Channels](/guide/data/data-channels) - Sending and receiving arbitrary data between peers +- [File Transfer](/guide/data/file-transfer) - Sending files with progress, confirmation, checksum and resume ## Networking and ICE diff --git a/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/FileTransferExample.java b/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/FileTransferExample.java new file mode 100644 index 000000000..c79f53cf8 --- /dev/null +++ b/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/FileTransferExample.java @@ -0,0 +1,125 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.examples; + +import java.nio.file.Files; +import java.nio.file.Path; +import java.nio.file.Paths; +import java.util.Arrays; +import java.util.Random; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.TimeUnit; + +import dev.onvoid.webrtc.client.AudioMode; +import dev.onvoid.webrtc.client.Peer; +import dev.onvoid.webrtc.client.PeerOptions; +import dev.onvoid.webrtc.client.Signaling; +import dev.onvoid.webrtc.client.SignalingPair; +import dev.onvoid.webrtc.client.WebRtc; +import dev.onvoid.webrtc.client.transfer.FileTransfers; +import dev.onvoid.webrtc.client.transfer.IncomingTransfer; +import dev.onvoid.webrtc.client.transfer.OutgoingTransfer; + +/** + * Example of file transfer over a data channel ({@code dev.onvoid.webrtc.client.transfer}): two + * peers in one process, one sends a file, the other saves it. + *

+ * This example shows how to: + *

+ *

+ * Pass a file to send, or a size in MiB for a file of random data, 20 by default: + *

+ * mvn exec:java -D"exec.mainClass=dev.onvoid.webrtc.examples.FileTransferExample" -D"exec.args=50"
+ * 
+ * + * @author Alex Andres + */ +public class FileTransferExample { + + public static void main(String[] args) throws Exception { + Path downloads = Files.createTempDirectory("webrtc-downloads"); + Path source = source(args.length > 0 ? args[0] : "20"); + + try (WebRtc rtc = WebRtc.builder().audio(AudioMode.HEADLESS).build()) { + // Both peers in one process. A real application signals through its own server. + SignalingPair link = Signaling.loopback(); + Peer sender = rtc.createPeer(PeerOptions.builder() + .name("sender") + .signaling(link.first()) + .build()); + Peer receiver = rtc.createPeer(PeerOptions.builder() + .name("receiver") + .signaling(link.second()) + .polite(true) + .build()); + + CompletableFuture incoming = new CompletableFuture<>(); + + receiver.onChannel(channel -> { + if (!channel.label().equals("files")) { + return; + } + + FileTransfers.over(channel).onOffer(offer -> { + // The name comes from the remote peer: never use it as a path as it is. + System.out.printf("Receiver is offered %s, %d bytes%n", offer.safeFileName(), offer.size()); + incoming.complete(offer.accept(downloads.resolve(offer.safeFileName()))); + }); + }); + + FileTransfers files = FileTransfers.over(sender.createChannel("files")); + OutgoingTransfer upload = files.send(source); + + upload.onProgress(progress -> System.out.printf("Receiver confirmed %.0f%% (%d of %d bytes)%n", + 100 * progress.fraction(), progress.bytes(), progress.size())); + + // The main thread may wait; a handler must not. + upload.whenDone().get(60, TimeUnit.SECONDS); + + IncomingTransfer received = incoming.get(5, TimeUnit.SECONDS); + received.whenDone().get(5, TimeUnit.SECONDS); + + boolean same = Arrays.equals(Files.readAllBytes(source), Files.readAllBytes(received.file())); + + System.out.println("Receiver saved " + received.file() + (same ? ", identical to " : ", differing from ") + + source); + } + } + + /** + * @return the file named, or a new file of random data of that many MiB. + */ + private static Path source(String argument) throws Exception { + Path file = Paths.get(argument); + + if (Files.isRegularFile(file)) { + return file; + } + + byte[] data = new byte[Integer.parseInt(argument) * 1024 * 1024]; + new Random().nextBytes(data); + + Path random = Files.createTempFile("webrtc-upload", ".bin"); + random.toFile().deleteOnExit(); + return Files.write(random, data); + } +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/FileTransfers.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/FileTransfers.java new file mode 100644 index 000000000..65ed80718 --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/FileTransfers.java @@ -0,0 +1,1121 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.client.transfer; + +import static java.util.Objects.requireNonNull; + +import java.io.EOFException; +import java.io.IOException; +import java.net.ProtocolException; +import java.nio.ByteBuffer; +import java.nio.channels.FileChannel; +import java.nio.file.AtomicMoveNotSupportedException; +import java.nio.file.FileSystemException; +import java.nio.file.Files; +import java.nio.file.Path; +import java.nio.file.StandardCopyOption; +import java.nio.file.StandardOpenOption; +import java.security.MessageDigest; +import java.security.SecureRandom; +import java.util.ArrayDeque; +import java.util.ArrayList; +import java.util.List; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.CompletionException; +import java.util.concurrent.Executor; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Executors; +import java.util.concurrent.RejectedExecutionException; +import java.util.concurrent.atomic.AtomicBoolean; +import java.util.concurrent.atomic.AtomicLong; +import java.util.function.Consumer; + +import dev.onvoid.webrtc.client.ChannelState; +import dev.onvoid.webrtc.client.DataChannel; +import dev.onvoid.webrtc.client.Message; +import dev.onvoid.webrtc.client.PeerClosedException; +import dev.onvoid.webrtc.client.Subscription; + +/** + * Sends and receives files over a {@link DataChannel}, which it takes over: + * both peers create one over their end of the channel, and nothing else may + * be sent on it. + *
{@code
+ * FileTransfers files = FileTransfers.over(peer.createChannel("files"));
+ *
+ * OutgoingTransfer upload = files.send(Paths.get("report.pdf"));
+ * upload.onProgress(p -> System.out.printf("%.0f%%%n", 100 * p.fraction()));
+ * upload.whenDone().thenRun(() -> System.out.println("The receiver has it"));
+ *
+ * // On the other side:
+ * peer.onChannel(channel -> {
+ *     if (channel.label().equals("files")) {
+ *         FileTransfers.over(channel).onOffer(offer ->
+ *                 offer.accept(downloads.resolve(offer.safeFileName())));
+ *     }
+ * });
+ * }
+ *

+ * A {@code send} future of the channel completes once the data is handed to + * the transport, which says nothing about the receiver. The protocol confirms + * on its own: the receiver acknowledges what it wrote to its file, and the + * sender never has more than the receiver's {@linkplain + * TransferOptions.Builder#window(int) window} unconfirmed, so a slow disk + * slows the sender down instead of filling memory. A transfer is done once + * the receiver found the SHA-256 of the whole file to match the sender's and + * moved the file into place. + *

+ * Files go one at a time in each direction, in the order they were sent; both + * peers may send at once. Each side reads and writes its files and runs the + * handlers on a thread of its own, never on the peer's event thread. + *

+ * When the channel closes, transfers fail with a {@link + * TransferException#isResumable() resumable} error. The sender may then + * {@linkplain #resume(OutgoingTransfer) resume} one over a new channel, say + * of a new peer once the connection was set up again, and the receiver + * continues where it stopped once it accepts the offer with the same target. + */ +public final class FileTransfers implements AutoCloseable { + + private static final System.Logger LOGGER = System.getLogger(FileTransfers.class.getName()); + + private static final SecureRandom RANDOM = new SecureRandom(); + + /** How much of a file is hashed in one go before a resume, between other work. */ + private static final int HASH_STEP = 1024 * 1024; + + private final DataChannel channel; + + private final TransferOptions options; + + private final Executor executor; + + /** The thread this created for itself, or null with an injected one. */ + private final ExecutorService ownExecutor; + + /** The most bytes of received messages that may wait for the thread. */ + private final long inboundLimit; + + /** Bytes of received messages that wait for the thread. */ + private final AtomicLong inbound = new AtomicLong(); + + /** Set once received messages went over {@link #inboundLimit}. */ + private final AtomicBoolean overflowed = new AtomicBoolean(); + + private final CompletableFuture closed = new CompletableFuture<>(); + + /** The bytes received after which this side acknowledges them. */ + private final long ackInterval; + + /** The most bytes of DATA frames whose send futures may be open. */ + private final long unsentLimit; + + // Confined to the thread. + + private boolean shut; + + private TransferException closeError; + + private Subscription messageSubscription; + + private Subscription stateSubscription; + + private final ArrayDeque queue = new ArrayDeque<>(); + + private Outgoing sending; + + private long unsent; + + /** The remote peer's offer that was neither accepted nor rejected yet. */ + private TransferOffer offer; + + private Incoming receiving; + + private final List> offerHandlers = new ArrayList<>(); + + + private FileTransfers(DataChannel channel, TransferOptions options, Executor executor) { + this.channel = channel; + this.options = options; + + if (executor == null) { + String name = "webrtc-transfer-" + channel.label(); + this.ownExecutor = Executors.newSingleThreadExecutor(task -> { + Thread thread = new Thread(task, name); + thread.setDaemon(true); + return thread; + }); + this.executor = ownExecutor; + } + else { + this.ownExecutor = null; + this.executor = executor; + } + + this.ackInterval = Math.max(TransferOptions.MIN_CHUNK_SIZE, options.window / 4); + this.unsentLimit = 4L * options.chunkSize; + // The window, its frame headers and room for the control frames. + this.inboundLimit = options.window + options.window / 8 + 64 * 1024; + } + + /** + * Takes over a channel with the default options. + * + * @param channel the channel, which carries nothing else from now on. + * + * @return the file transfers over the channel. + */ + public static FileTransfers over(DataChannel channel) { + return over(channel, TransferOptions.defaults()); + } + + /** + * Takes over a channel. Messages that arrived on it before are kept for + * it, as the channel keeps them for its next handler. + * + * @param channel the channel, which carries nothing else from now on. + * @param options how to send and receive. + * + * @return the file transfers over the channel. + */ + public static FileTransfers over(DataChannel channel, TransferOptions options) { + return over(channel, options, null); + } + + /** With a serial executor of the test's in place of a thread of its own. */ + static FileTransfers over(DataChannel channel, TransferOptions options, Executor executor) { + requireNonNull(channel, "channel"); + requireNonNull(options, "options"); + + FileTransfers transfers = new FileTransfers(channel, options, executor); + + // Subscribed on the thread, which so owns the subscriptions from the + // start. The channel keeps what arrives until then. + transfers.post(transfers::subscribe, () -> {}); + + return transfers; + } + + /** + * Sends a file under its own name. + * + * @param file the file, opened before this returns and read as it is + * sent. + * + * @return the transfer, which starts once the transfers before it are + * done. + * + * @throws IOException if the file cannot be opened. + */ + public OutgoingTransfer send(Path file) throws IOException { + requireNonNull(file, "file"); + + if (file.getFileName() == null) { + throw new IllegalArgumentException("The path " + file + " names no file"); + } + + return send(file, file.getFileName().toString()); + } + + /** + * Sends a file under the name given. + * + * @param file the file, opened before this returns and read as it is + * sent. + * @param name the name the receiver sees, at most 1024 bytes of UTF-8. + * + * @return the transfer, which starts once the transfers before it are + * done. + * + * @throws IOException if the file cannot be opened. + */ + public OutgoingTransfer send(Path file, String name) throws IOException { + requireNonNull(file, "file"); + requireNonNull(name, "name"); + Frames.utf8(name); + + return start(file, name, newId()); + } + + /** + * Sends a file again whose transfer failed with a {@linkplain + * TransferException#isResumable() resumable} error, as one of the same id + * and name. The receiver continues where it stopped once it accepts the + * offer with the same target, and the checksum covers the whole file. + * + * @param previous the transfer that failed, of these or of other file + * transfers. + * + * @return the new transfer. + * + * @throws IOException if the file cannot be opened. + * @throws IllegalStateException if the transfer is not done, or failed in + * a way that cannot be resumed. + */ + public OutgoingTransfer resume(OutgoingTransfer previous) throws IOException { + requireNonNull(previous, "previous"); + + if (!(previous instanceof Outgoing)) { + throw new IllegalArgumentException("Not a transfer of FileTransfers: " + previous); + } + + Outgoing failed = (Outgoing) previous; + TransferException failure = failed.failure; + + if (failure == null || !failure.isResumable()) { + throw new IllegalStateException("The transfer " + failed.id + " did not fail in a way that can be resumed"); + } + + return start(failed.path, failed.name, failed.id); + } + + /** + * Calls the handler with each file the remote peer offers. One offered + * while there is no handler waits for the next one. + * + * @param handler called on the thread of these file transfers; it accepts + * or rejects the offer, then or later. + * + * @return the subscription that removes the handler. + */ + public Subscription onOffer(Consumer handler) { + requireNonNull(handler, "handler"); + + post(() -> { + if (shut) { + return; + } + + offerHandlers.add(handler); + + if (offer != null && !offer.isDecided()) { + call(handler, offer); + } + }, () -> {}); + + return () -> post(() -> offerHandlers.remove(handler), () -> {}); + } + + /** + * @return a future that completes once these file transfers closed, + * exceptionally with a {@link TransferException} when the remote peer + * broke the protocol. + */ + public CompletableFuture whenClosed() { + return closed.copy(); + } + + /** + * Closes the channel. Transfers that are not done fail with a resumable + * {@link TransferException}. Never blocks, may be called more than once. + */ + @Override + public void close() { + post(() -> shutDown(new TransferException("The file transfers over the data channel " + channel.label() + + " were closed", true)), () -> {}); + } + + // Called by the transfers and offers, on any thread. + + Subscription subscribe(TransferImpl transfer, Consumer handler) { + post(() -> { + if (!transfer.isDone()) { + transfer.progressHandlers.add(handler); + } + call(handler, transfer.progress); + }, () -> {}); + + return () -> transfer.progressHandlers.remove(handler); + } + + void cancel(TransferImpl transfer) { + post(() -> cancelHere(transfer), () -> {}); + } + + IncomingTransfer accept(TransferOffer accepted, Path target) { + Incoming transfer = new Incoming(this, accepted, target); + + post(() -> begin(transfer), () -> transfer.finish(closedError())); + + return transfer; + } + + void reject(TransferOffer rejected, String reason) { + post(() -> { + if (offer == rejected) { + offer = null; + sendControl(Frames.reject(rejected.id(), reason)); + } + }, () -> {}); + } + + // The thread. + + /** + * Runs the task on the thread, or the fallback if the thread is gone, so + * that what the task would complete never stays open. + */ + private void post(Runnable task, Runnable dropped) { + try { + executor.execute(task); + } + catch (RejectedExecutionException e) { + dropped.run(); + } + } + + private void subscribe() { + if (shut) { + return; + } + + messageSubscription = channel.onMessage(this::received); + stateSubscription = channel.onStateChange(state -> { + if (state == ChannelState.CLOSING || state == ChannelState.CLOSED) { + post(() -> shutDown(new TransferException("The data channel " + channel.label() + " closed", true)), + () -> {}); + } + }); + } + + /** + * Takes a message on the peer's event thread and passes it on. What waits + * for the thread is bounded: a peer that keeps to the protocol never has + * more than a window of data unconfirmed. + */ + private void received(Message message) { + if (overflowed.get()) { + return; + } + + int size = message.size(); + + if (inbound.addAndGet(size) > inboundLimit) { + inbound.addAndGet(-size); + + if (overflowed.compareAndSet(false, true)) { + post(() -> protocolError("it sent more than the window of " + options.window + " bytes allows"), + () -> {}); + } + return; + } + + boolean text = message.isText(); + byte[] data = message.bytes(); + + post(() -> { + inbound.addAndGet(-size); + handle(text, data); + }, () -> inbound.addAndGet(-size)); + } + + private void handle(boolean text, byte[] message) { + if (shut) { + return; + } + if (text) { + protocolError("it sent a text message"); + return; + } + + Frames.Frame frame; + + try { + frame = Frames.decode(message); + } + catch (ProtocolException e) { + protocolError(e.getMessage()); + return; + } + + switch (frame.type) { + case Frames.OFFER: + offered(frame); + break; + case Frames.ACCEPT: + accepted(frame); + break; + case Frames.REJECT: + rejected(frame); + break; + case Frames.DATA: + data(frame); + break; + case Frames.ACK: + acknowledged(frame); + break; + case Frames.END: + ended(frame); + break; + case Frames.DONE: + confirmed(frame); + break; + case Frames.CANCEL: + cancelled(frame); + break; + default: + protocolError("unknown frame type " + frame.type); + } + } + + // Sending. + + private Outgoing start(Path file, String name, String id) throws IOException { + if (!Files.isRegularFile(file)) { + throw new FileSystemException(file.toString(), null, "Not a regular file"); + } + + FileChannel source = FileChannel.open(file, StandardOpenOption.READ); + Outgoing transfer; + + try { + transfer = new Outgoing(this, id, name, source.size(), file, source); + } + catch (IOException | RuntimeException e) { + source.close(); + throw e; + } + + post(() -> { + if (shut) { + transfer.finish(closedError()); + return; + } + + queue.add(transfer); + next(); + }, () -> transfer.finish(closedError())); + + return transfer; + } + + /** Offers the next file once the one before is done. */ + private void next() { + while (sending == null && !shut && !queue.isEmpty()) { + Outgoing transfer = queue.poll(); + + if (transfer.isDone()) { + continue; + } + + sending = transfer; + transfer.state = TransferImpl.State.OFFERED; + sendControl(Frames.offer(transfer.id, transfer.size, transfer.name)); + } + } + + private void accepted(Frames.Frame frame) { + Outgoing transfer = sending(frame); + + if (transfer == null) { + return; + } + if (transfer.state != TransferImpl.State.OFFERED) { + protocolError("it accepted " + frame.id + " twice"); + return; + } + if (frame.value < 0 || frame.value > transfer.size || frame.window <= 0) { + protocolError("it accepted " + frame.id + " from offset " + frame.value + " with a window of " + + frame.window); + return; + } + + transfer.next = frame.value; + transfer.acked = frame.value; + transfer.window = frame.window; + transfer.state = TransferImpl.State.HASHING; + progress(transfer, frame.value); + + hash(transfer, frame.value, () -> { + transfer.state = TransferImpl.State.TRANSFERRING; + pump(); + }, error -> abort(transfer, "Reading " + transfer.path + " failed", error)); + } + + /** Sends chunks while the receiver's window and the channel have room. */ + private void pump() { + Outgoing transfer = sending; + + if (shut || transfer == null || transfer.state != TransferImpl.State.TRANSFERRING) { + return; + } + + while (transfer.next < transfer.size && transfer.next - transfer.acked < transfer.window + && unsent < unsentLimit) { + long room = transfer.acked + transfer.window - transfer.next; + int length = (int) Math.min(options.chunkSize, Math.min(transfer.size - transfer.next, room)); + byte[] frame = Frames.data(transfer.id, transfer.next, length); + + try { + readFully(transfer.file, ByteBuffer.wrap(frame, Frames.DATA_HEADER, length), transfer.next); + } + catch (EOFException e) { + abort(transfer, transfer.path + " got shorter than the " + transfer.size + " bytes offered", e); + return; + } + catch (IOException e) { + abort(transfer, "Reading " + transfer.path + " failed", e); + return; + } + + transfer.digest.update(frame, Frames.DATA_HEADER, length); + transfer.next += length; + unsent += frame.length; + + int size = frame.length; + + channel.send(frame).whenComplete((result, error) -> post(() -> { + unsent -= size; + + if (error != null) { + sendFailed(error); + } + else { + pump(); + } + }, () -> {})); + } + + if (transfer.next == transfer.size && !transfer.endSent) { + transfer.endSent = true; + sendControl(Frames.end(transfer.id, transfer.digest.digest())); + } + } + + private void acknowledged(Frames.Frame frame) { + Outgoing transfer = sending(frame); + + if (transfer == null) { + return; + } + if (transfer.state != TransferImpl.State.TRANSFERRING || frame.value < transfer.acked + || frame.value > transfer.next) { + protocolError("it acknowledged " + frame.value + " bytes of " + frame.id + ", of which " + + transfer.next + " were sent"); + return; + } + + transfer.acked = frame.value; + progress(transfer, frame.value); + pump(); + } + + private void confirmed(Frames.Frame frame) { + Outgoing transfer = sending(frame); + + if (transfer == null) { + return; + } + if (!transfer.endSent) { + protocolError("it confirmed " + frame.id + " before it got all of it"); + return; + } + + if (transfer.progress.bytes() != transfer.size) { + progress(transfer, transfer.size); + } + + transfer.finish(null); + endSending(transfer); + } + + private void rejected(Frames.Frame frame) { + Outgoing transfer = sending(frame); + + if (transfer == null) { + return; + } + if (transfer.state != TransferImpl.State.OFFERED) { + protocolError("it rejected " + frame.id + " after it accepted it"); + return; + } + + transfer.finish(new TransferException("The remote peer rejected " + transfer.name + ": " + + Frames.printable(frame.text), false)); + endSending(transfer); + } + + /** Tells the receiver the transfer failed, and ends it. */ + private void abort(Outgoing transfer, String reason, Throwable cause) { + sendControl(Frames.cancel(transfer.id, true, reason)); + transfer.finish(new TransferException(reason, cause, false)); + endSending(transfer); + } + + private void endSending(Outgoing transfer) { + if (sending == transfer) { + sending = null; + next(); + } + else { + queue.remove(transfer); + } + } + + /** @return the transfer sent now if the frame is about it, else null. */ + private Outgoing sending(Frames.Frame frame) { + // A frame for another one was on its way when this side ended that. + return sending != null && sending.id.equals(frame.id) ? sending : null; + } + + // Receiving. + + private void offered(Frames.Frame frame) { + if (frame.version != Frames.VERSION) { + sendControl(Frames.reject(frame.id, "Version " + frame.version + " of the protocol is not supported")); + return; + } + if (offer != null || receiving != null) { + protocolError("it offered " + frame.id + " while another transfer was not done"); + return; + } + if (frame.value < 0) { + protocolError("it offered " + frame.id + " with a size of " + frame.value); + return; + } + + offer = new TransferOffer(this, frame.id, frame.text, frame.value); + + for (Consumer handler : new ArrayList<>(offerHandlers)) { + if (offer == null || offer.isDecided()) { + break; + } + call(handler, offer); + } + } + + /** Opens the partial file of an accepted offer and accepts from where it ends. */ + private void begin(Incoming transfer) { + if (shut) { + transfer.finish(closedError()); + return; + } + if (offer != transfer.offer) { + transfer.finish(new TransferCancelledException("The remote peer cancelled the transfer of " + + transfer.id + " before it was accepted")); + return; + } + + offer = null; + + if (transfer.isDone()) { + // Cancelled before it began. + sendControl(Frames.reject(transfer.id, "Cancelled")); + return; + } + + receiving = transfer; + transfer.state = TransferImpl.State.HASHING; + + long offset = 0; + + try { + if (options.resumable && Files.isRegularFile(transfer.part)) { + offset = Files.size(transfer.part); + + if (offset > transfer.size) { + offset = 0; + } + } + + transfer.file = FileChannel.open(transfer.part, StandardOpenOption.CREATE, StandardOpenOption.READ, + StandardOpenOption.WRITE); + transfer.file.truncate(offset); + } + catch (IOException e) { + refuse(transfer, e); + return; + } + + long start = offset; + + hash(transfer, start, () -> { + transfer.state = TransferImpl.State.TRANSFERRING; + transfer.written = start; + transfer.acked = start; + progress(transfer, start); + sendControl(Frames.accept(transfer.id, start, options.window)); + }, error -> refuse(transfer, error)); + } + + /** Rejects an accepted offer whose partial file cannot be used. */ + private void refuse(Incoming transfer, IOException cause) { + String reason = "The receiver cannot write the file"; + + sendControl(Frames.reject(transfer.id, reason)); + receiving = null; + transfer.closeFile(); + delete(transfer.part); + transfer.finish(new TransferException(reason + " " + transfer.part, cause, false)); + } + + private void data(Frames.Frame frame) { + Incoming transfer = receiving(frame); + + if (transfer == null) { + return; + } + + long end = frame.value + frame.payloadLength; + + if (transfer.state != TransferImpl.State.TRANSFERRING) { + protocolError("it sent data of " + frame.id + " before it was accepted"); + return; + } + if (frame.value != transfer.written || frame.payloadLength == 0) { + protocolError("it sent " + frame.payloadLength + " bytes of " + frame.id + " at offset " + frame.value + + " where " + transfer.written + " were expected"); + return; + } + if (end > transfer.size) { + protocolError("it sent more of " + frame.id + " than the " + transfer.size + " bytes offered"); + return; + } + if (end > transfer.acked + options.window) { + protocolError("it sent more of " + frame.id + " than the window of " + options.window + " bytes allows"); + return; + } + + try { + ByteBuffer payload = ByteBuffer.wrap(frame.payload, frame.payloadOffset, frame.payloadLength); + long position = transfer.written; + + while (payload.hasRemaining()) { + position += transfer.file.write(payload, position); + } + } + catch (IOException e) { + failReceiving(transfer, "Writing " + transfer.part + " failed", e); + return; + } + + transfer.digest.update(frame.payload, frame.payloadOffset, frame.payloadLength); + transfer.written = end; + + if (transfer.written - transfer.acked >= ackInterval || transfer.written == transfer.size) { + transfer.acked = transfer.written; + sendControl(Frames.ack(transfer.id, transfer.acked)); + progress(transfer, transfer.acked); + } + } + + /** Checks the whole file and moves it into place. */ + private void ended(Frames.Frame frame) { + Incoming transfer = receiving(frame); + + if (transfer == null) { + return; + } + if (transfer.state != TransferImpl.State.TRANSFERRING || transfer.written != transfer.size) { + protocolError("it ended " + frame.id + " after " + transfer.written + " of " + transfer.size + " bytes"); + return; + } + if (!MessageDigest.isEqual(transfer.digest.digest(), frame.digest)) { + failReceiving(transfer, "The SHA-256 of the received file " + transfer.path + " does not match the " + + "sender's", null); + return; + } + + try { + transfer.file.force(true); + transfer.file.close(); + move(transfer.part, transfer.path); + } + catch (IOException e) { + failReceiving(transfer, "Moving the received file to " + transfer.path + " failed", e); + return; + } + + receiving = null; + sendControl(Frames.done(transfer.id)); + transfer.finish(null); + } + + /** Tells the sender the transfer failed, and ends it. */ + private void failReceiving(Incoming transfer, String reason, Throwable cause) { + sendControl(Frames.cancel(transfer.id, true, reason)); + receiving = null; + transfer.closeFile(); + delete(transfer.part); + transfer.finish(new TransferException(reason, cause, false)); + } + + /** @return the transfer received now if the frame is about it, else null. */ + private Incoming receiving(Frames.Frame frame) { + return receiving != null && receiving.id.equals(frame.id) ? receiving : null; + } + + // Both directions. + + private void cancelled(Frames.Frame frame) { + String reason = frame.text.isEmpty() ? "" : ": " + Frames.printable(frame.text); + + Outgoing outgoing = sending(frame); + + if (outgoing != null) { + outgoing.finish(remoteEnd(frame, outgoing.name, reason)); + endSending(outgoing); + return; + } + + Incoming incoming = receiving(frame); + + if (incoming != null) { + receiving = null; + incoming.closeFile(); + delete(incoming.part); + incoming.finish(remoteEnd(frame, incoming.path.toString(), reason)); + return; + } + + if (offer != null && offer.id().equals(frame.id)) { + // An accept that follows finds the offer gone. + offer = null; + } + } + + private static TransferException remoteEnd(Frames.Frame frame, String name, String reason) { + return frame.failed + ? new TransferException("The remote peer stopped the transfer of " + name + reason, false) + : new TransferCancelledException("The remote peer cancelled the transfer of " + name + reason); + } + + private void cancelHere(TransferImpl transfer) { + if (transfer.isDone()) { + return; + } + + TransferCancelledException cancelled = new TransferCancelledException("The transfer " + transfer.id + + " was cancelled"); + + if (transfer instanceof Outgoing) { + Outgoing outgoing = (Outgoing) transfer; + + if (sending == outgoing) { + sendControl(Frames.cancel(outgoing.id, false, "")); + } + + outgoing.finish(cancelled); + endSending(outgoing); + } + else { + Incoming incoming = (Incoming) transfer; + + if (receiving == incoming) { + sendControl(Frames.cancel(incoming.id, false, "")); + receiving = null; + } + + incoming.closeFile(); + delete(incoming.part); + incoming.finish(cancelled); + } + } + + /** + * Hashes the first bytes of a transfer's file a step at a time, so that + * a large file does not hold up the other direction, then runs the next + * step unless the transfer ended meanwhile. + */ + private void hash(TransferImpl transfer, long end, Runnable then, Consumer failed) { + ByteBuffer buffer = ByteBuffer.allocate((int) Math.max(1, Math.min(HASH_STEP, end))); + + hashStep(transfer, 0, end, buffer, then, failed); + } + + private void hashStep(TransferImpl transfer, long position, long end, ByteBuffer buffer, Runnable then, + Consumer failed) { + if (shut || transfer.isDone()) { + return; + } + if (position == end) { + then.run(); + return; + } + + buffer.clear(); + buffer.limit((int) Math.min(buffer.capacity(), end - position)); + + try { + readFully(transfer.file, buffer, position); + } + catch (IOException e) { + failed.accept(e); + return; + } + + transfer.digest.update(buffer.array(), 0, buffer.limit()); + + long next = position + buffer.limit(); + + post(() -> hashStep(transfer, next, end, buffer, then, failed), () -> {}); + } + + private void progress(TransferImpl transfer, long bytes) { + TransferProgress progress = new TransferProgress(bytes, transfer.size); + transfer.progress = progress; + + for (Consumer handler : transfer.progressHandlers) { + call(handler, progress); + } + } + + private void sendControl(byte[] frame) { + channel.send(frame).whenComplete((result, error) -> { + if (error != null) { + post(() -> sendFailed(error), () -> {}); + } + }); + } + + private void sendFailed(Throwable error) { + Throwable cause = error instanceof CompletionException && error.getCause() != null ? error.getCause() : error; + + shutDown(new TransferException("Sending on the data channel " + channel.label() + " failed", cause, + cause instanceof PeerClosedException)); + } + + /** + * Ends the transfers, tells the remote peer of those it takes part in, + * and closes the channel. + */ + private void protocolError(String what) { + if (shut) { + return; + } + + String reason = "The remote peer broke the file transfer protocol: " + what; + List> told = new ArrayList<>(); + + if (sending != null) { + told.add(channel.send(Frames.cancel(sending.id, true, reason))); + } + if (receiving != null) { + told.add(channel.send(Frames.cancel(receiving.id, true, reason))); + } + + // The channel drops on close what it has not handed to the transport. + shutDown(new TransferException(reason, false), CompletableFuture.allOf(told.toArray(new CompletableFuture[0]))); + } + + private void shutDown(TransferException error) { + shutDown(error, CompletableFuture.completedFuture(null)); + } + + private void shutDown(TransferException error, CompletableFuture beforeClose) { + if (shut) { + return; + } + + shut = true; + closeError = error; + + if (sending != null) { + sending.finish(error); + sending = null; + } + + for (Outgoing transfer : queue) { + transfer.finish(error); + } + queue.clear(); + + if (receiving != null) { + receiving.closeFile(); + + if (!error.isResumable() || !options.resumable) { + delete(receiving.part); + } + + receiving.finish(error); + receiving = null; + } + + offer = null; + offerHandlers.clear(); + + if (messageSubscription != null) { + messageSubscription.close(); + stateSubscription.close(); + } + + beforeClose.whenComplete((result, failure) -> channel.close()); + + if (ownExecutor != null) { + ownExecutor.shutdown(); + } + + if (error.isResumable()) { + closed.complete(null); + } + else { + closed.completeExceptionally(error); + } + } + + private TransferException closedError() { + TransferException error = closeError; + + return error != null ? error : new TransferException("The file transfers over the data channel " + + channel.label() + " are closed", true); + } + + private static void call(Consumer handler, T value) { + try { + handler.accept(value); + } + catch (Throwable e) { + LOGGER.log(System.Logger.Level.WARNING, "A file transfer handler failed", e); + } + } + + private static void readFully(FileChannel file, ByteBuffer buffer, long position) throws IOException { + while (buffer.hasRemaining()) { + int read = file.read(buffer, position); + + if (read < 0) { + throw new EOFException("The file ends at " + position); + } + + position += read; + } + } + + private static void move(Path from, Path to) throws IOException { + try { + Files.move(from, to, StandardCopyOption.ATOMIC_MOVE, StandardCopyOption.REPLACE_EXISTING); + } + catch (AtomicMoveNotSupportedException e) { + Files.move(from, to, StandardCopyOption.REPLACE_EXISTING); + } + } + + private static void delete(Path file) { + try { + Files.deleteIfExists(file); + } + catch (IOException e) { + LOGGER.log(System.Logger.Level.WARNING, "Deleting " + file + " failed", e); + } + } + + private static String newId() { + byte[] id = new byte[Frames.ID_LENGTH]; + RANDOM.nextBytes(id); + return Frames.hex(id); + } +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/Frames.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/Frames.java new file mode 100644 index 000000000..d21699faf --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/Frames.java @@ -0,0 +1,300 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.client.transfer; + +import java.net.ProtocolException; +import java.nio.BufferUnderflowException; +import java.nio.ByteBuffer; +import java.nio.CharBuffer; +import java.nio.charset.CharsetEncoder; +import java.nio.charset.CodingErrorAction; +import java.nio.charset.StandardCharsets; + +/** + * The frames of the transfer protocol, one binary data channel message each. + * All numbers are big-endian. Every frame starts with its type and the 16 + * bytes of the transfer id: + *

+ * OFFER  1  id  version:u8  size:u64  name:text
+ * ACCEPT 2  id  offset:u64  window:u32
+ * REJECT 3  id  reason:text
+ * DATA   4  id  offset:u64  payload (the rest of the message)
+ * ACK    5  id  offset:u64
+ * END    6  id  sha256:32 bytes
+ * DONE   7  id
+ * CANCEL 8  id  failed:u8  reason:text
+ * 
+ * A text is a u16 length followed by that many bytes of UTF-8, at most + * {@link #MAX_TEXT}. + */ +final class Frames { + + static final int VERSION = 1; + + static final byte OFFER = 1; + static final byte ACCEPT = 2; + static final byte REJECT = 3; + static final byte DATA = 4; + static final byte ACK = 5; + static final byte END = 6; + static final byte DONE = 7; + static final byte CANCEL = 8; + + static final int ID_LENGTH = 16; + + static final int DIGEST_LENGTH = 32; + + /** Bytes of a DATA frame before its payload. */ + static final int DATA_HEADER = 1 + ID_LENGTH + 8; + + /** The most bytes of UTF-8 a name or a reason may take. */ + static final int MAX_TEXT = 1024; + + + private Frames() { + } + + static byte[] offer(String id, long size, String name) { + byte[] text = utf8(name); + ByteBuffer frame = start(OFFER, id, 1 + 8 + 2 + text.length); + frame.put((byte) VERSION).putLong(size).putShort((short) text.length).put(text); + return frame.array(); + } + + static byte[] accept(String id, long offset, int window) { + return start(ACCEPT, id, 8 + 4).putLong(offset).putInt(window).array(); + } + + static byte[] reject(String id, String reason) { + byte[] text = truncated(reason); + return start(REJECT, id, 2 + text.length).putShort((short) text.length).put(text).array(); + } + + /** + * @return a DATA frame whose payload, {@code length} bytes from {@link + * #DATA_HEADER} on, the caller fills. + */ + static byte[] data(String id, long offset, int length) { + return start(DATA, id, 8 + length).putLong(offset).array(); + } + + static byte[] ack(String id, long offset) { + return start(ACK, id, 8).putLong(offset).array(); + } + + static byte[] end(String id, byte[] digest) { + return start(END, id, DIGEST_LENGTH).put(digest).array(); + } + + static byte[] done(String id) { + return start(DONE, id, 0).array(); + } + + static byte[] cancel(String id, boolean failed, String reason) { + byte[] text = truncated(reason); + ByteBuffer frame = start(CANCEL, id, 1 + 2 + text.length); + frame.put((byte) (failed ? 1 : 0)).putShort((short) text.length).put(text); + return frame.array(); + } + + /** + * @param message a whole binary message. + * + * @return the frame it holds. + * + * @throws ProtocolException if it holds none. + */ + static Frame decode(byte[] message) throws ProtocolException { + ByteBuffer in = ByteBuffer.wrap(message); + Frame frame = new Frame(); + + try { + frame.type = in.get(); + + byte[] id = new byte[ID_LENGTH]; + in.get(id); + frame.id = hex(id); + + switch (frame.type) { + case OFFER: + frame.version = in.get() & 0xff; + // A later version may lay out the rest differently. + if (frame.version == VERSION) { + frame.value = in.getLong(); + frame.text = text(in); + } + break; + case ACCEPT: + frame.value = in.getLong(); + frame.window = in.getInt(); + break; + case REJECT: + frame.text = text(in); + break; + case DATA: + frame.value = in.getLong(); + frame.payload = message; + frame.payloadOffset = DATA_HEADER; + frame.payloadLength = message.length - DATA_HEADER; + in.position(message.length); + break; + case ACK: + frame.value = in.getLong(); + break; + case END: + frame.digest = new byte[DIGEST_LENGTH]; + in.get(frame.digest); + break; + case DONE: + break; + case CANCEL: + frame.failed = in.get() != 0; + frame.text = text(in); + break; + default: + throw new ProtocolException("Unknown frame type " + frame.type); + } + } + catch (BufferUnderflowException e) { + throw new ProtocolException("A frame of type " + frame.type + " ends early"); + } + + if (in.hasRemaining() && !(frame.type == OFFER && frame.version != VERSION)) { + throw new ProtocolException("A frame of type " + frame.type + " has " + in.remaining() + + " bytes too many"); + } + + return frame; + } + + /** + * @return the UTF-8 of the text. + * + * @throws IllegalArgumentException if it takes more than {@link #MAX_TEXT} + * bytes. + */ + static byte[] utf8(String text) { + byte[] bytes = text.getBytes(StandardCharsets.UTF_8); + + if (bytes.length > MAX_TEXT) { + throw new IllegalArgumentException("The name takes " + bytes.length + " bytes of UTF-8, more than " + + MAX_TEXT); + } + + return bytes; + } + + /** + * Escapes what the remote peer wrote before it goes into an exception + * message, so that it cannot forge log lines. + */ + static String printable(String text) { + StringBuilder printable = new StringBuilder(text.length()); + + for (int i = 0; i < text.length(); i++) { + char c = text.charAt(i); + + if (Character.isISOControl(c) || Character.getType(c) == Character.FORMAT + || c == '\u2028' || c == '\u2029') { + printable.append(String.format("\\u%04x", (int) c)); + } + else { + printable.append(c); + } + } + + return printable.toString(); + } + + static String hex(byte[] bytes) { + StringBuilder hex = new StringBuilder(bytes.length * 2); + + for (byte b : bytes) { + hex.append(Character.forDigit((b >>> 4) & 15, 16)).append(Character.forDigit(b & 15, 16)); + } + + return hex.toString(); + } + + private static ByteBuffer start(byte type, String id, int length) { + ByteBuffer frame = ByteBuffer.allocate(1 + ID_LENGTH + length); + frame.put(type); + + for (int i = 0; i < ID_LENGTH; i++) { + frame.put((byte) Integer.parseInt(id.substring(2 * i, 2 * i + 2), 16)); + } + + return frame; + } + + /** At most {@link #MAX_TEXT} bytes of UTF-8, cut at a character. */ + private static byte[] truncated(String text) { + CharsetEncoder encoder = StandardCharsets.UTF_8.newEncoder() + .onMalformedInput(CodingErrorAction.REPLACE) + .onUnmappableCharacter(CodingErrorAction.REPLACE); + ByteBuffer out = ByteBuffer.allocate(MAX_TEXT); + encoder.encode(CharBuffer.wrap(text == null ? "" : text), out, true); + + byte[] bytes = new byte[out.position()]; + out.flip(); + out.get(bytes); + return bytes; + } + + private static String text(ByteBuffer in) throws ProtocolException { + int length = in.getShort() & 0xffff; + + if (length > MAX_TEXT) { + throw new ProtocolException("A text of " + length + " bytes, more than " + MAX_TEXT); + } + + byte[] bytes = new byte[length]; + in.get(bytes); + return new String(bytes, StandardCharsets.UTF_8); + } + + + + /** A decoded frame. Which fields are set depends on the type. */ + static final class Frame { + + byte type; + + String id; + + int version; + + /** The size of an OFFER, or the offset of ACCEPT, DATA and ACK. */ + long value; + + int window; + + String text; + + byte[] digest; + + boolean failed; + + /** The message of a DATA frame, whose payload starts at {@link #payloadOffset}. */ + byte[] payload; + + int payloadOffset; + + int payloadLength; + + } +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/Incoming.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/Incoming.java new file mode 100644 index 000000000..3e3832ec6 --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/Incoming.java @@ -0,0 +1,50 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.client.transfer; + +import java.nio.file.Path; + +/** + * The {@link IncomingTransfer} of a {@link FileTransfers}. + */ +final class Incoming extends TransferImpl implements IncomingTransfer { + + final TransferOffer offer; + + final Path part; + + // Confined to the thread of the owner. + + /** The bytes written to the partial file. */ + long written; + + /** The bytes confirmed to the sender. */ + long acked; + + + Incoming(FileTransfers owner, TransferOffer offer, Path target) { + super(owner, offer.id(), offer.name(), offer.size(), target); + + this.offer = offer; + this.part = target.resolveSibling(target.getFileName() + "." + offer.id().substring(0, 16) + ".part"); + } + + @Override + public Path partialFile() { + return part; + } +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/IncomingTransfer.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/IncomingTransfer.java new file mode 100644 index 000000000..c96b9f9e2 --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/IncomingTransfer.java @@ -0,0 +1,41 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.client.transfer; + +import java.nio.file.Path; + +/** + * A file this side receives, from {@link TransferOffer#accept(Path)}. + *

+ * The data goes to {@link #partialFile()} next to the target, which only once + * the checksum matched replaces {@link #file()}. A transfer that failed with + * a {@link TransferException#isResumable() resumable} error leaves the partial + * file behind (unless {@link TransferOptions.Builder#resumable(boolean)} is + * off): when the sender resumes the transfer and the offer is accepted with + * the same target, it continues from there. An application that will not + * resume it deletes the partial file. + */ +public interface IncomingTransfer extends Transfer { + + /** + * @return the file the data is written to until it is complete: the + * target's name with the start of the transfer id and {@code .part} + * appended, in the target's directory. + */ + Path partialFile(); + +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/Outgoing.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/Outgoing.java new file mode 100644 index 000000000..2e5214b2b --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/Outgoing.java @@ -0,0 +1,58 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.client.transfer; + +import java.nio.channels.FileChannel; +import java.nio.file.Path; + +/** + * The {@link OutgoingTransfer} of a {@link FileTransfers}. It reads its file + * through a channel opened when it was created. + */ +final class Outgoing extends TransferImpl implements OutgoingTransfer { + + /** The failure it ended with, which decides whether it may be resumed. */ + volatile TransferException failure; + + // Confined to the thread of the owner. + + /** The offset of the next chunk to send. */ + long next; + + /** The bytes the receiver confirmed. */ + long acked; + + /** The bytes the receiver lets this side send beyond those it confirmed. */ + int window; + + boolean endSent; + + + Outgoing(FileTransfers owner, String id, String name, long size, Path source, FileChannel file) { + super(owner, id, name, size, source); + + this.file = file; + } + + @Override + void finish(TransferException error) { + if (!isDone()) { + failure = error; + } + super.finish(error); + } +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/OutgoingTransfer.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/OutgoingTransfer.java new file mode 100644 index 000000000..baecadfb2 --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/OutgoingTransfer.java @@ -0,0 +1,26 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.client.transfer; + +/** + * A file this side sends, created with {@link FileTransfers#send}. One that + * failed with a {@link TransferException#isResumable() resumable} error may be + * resumed with {@link FileTransfers#resume(OutgoingTransfer)}. + */ +public interface OutgoingTransfer extends Transfer { + +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/Transfer.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/Transfer.java new file mode 100644 index 000000000..09fa3f44c --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/Transfer.java @@ -0,0 +1,88 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.client.transfer; + +import java.nio.file.Path; +import java.util.concurrent.CompletableFuture; +import java.util.function.Consumer; + +import dev.onvoid.webrtc.client.Subscription; + +/** + * A file on its way to or from the remote peer, over {@link FileTransfers}. + *

+ * Handlers run on the thread of the {@link FileTransfers}, which also reads + * and writes the files, so they should not block. + */ +public interface Transfer { + + /** + * @return the id both peers know the transfer by, 32 hex digits. A + * resumed transfer keeps the id. + */ + String id(); + + /** + * @return the name the sender gave the file. + */ + String name(); + + /** + * @return the size of the file in bytes. + */ + long size(); + + /** + * @return the file read on this side, or for the receiver the file that + * holds the data once the transfer is done. + */ + Path file(); + + /** + * @return the bytes the receiver confirmed so far. + */ + TransferProgress progress(); + + /** + * Calls the handler with the current progress, and then each time the + * receiver confirms more data, a quarter of its window at a time and once + * the file is complete. + * + * @param handler called on the thread of the {@link FileTransfers}. + * + * @return the subscription that removes the handler. + */ + Subscription onProgress(Consumer handler); + + /** + * @return a future that completes once the receiver wrote the whole file, + * found its SHA-256 to match the sender's and moved it into place. It + * fails with a {@link TransferException}, a {@link + * TransferCancelledException} for a cancelled transfer. Each call returns + * a future of its own, so completing or cancelling it changes nothing for + * the transfer. + */ + CompletableFuture whenDone(); + + /** + * Cancels the transfer and tells the remote peer, unless it is done + * already. The receiver deletes the data it received. Never blocks, may be + * called more than once. + */ + void cancel(); + +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferCancelledException.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferCancelledException.java new file mode 100644 index 000000000..ff15984db --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferCancelledException.java @@ -0,0 +1,37 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.client.transfer; + +/** + * A file transfer was cancelled, on this side with {@link Transfer#cancel()} + * or by the remote peer. A cancelled transfer cannot be resumed. + */ +public class TransferCancelledException extends TransferException { + + private static final long serialVersionUID = 1L; + + + /** + * Creates the exception with a message that says who cancelled. + * + * @param message the detail message. + */ + public TransferCancelledException(String message) { + super(message, false); + } + +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferException.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferException.java new file mode 100644 index 000000000..7689da02b --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferException.java @@ -0,0 +1,69 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.client.transfer; + +import dev.onvoid.webrtc.client.WebRtcException; + +/** + * A file transfer did not complete: it was rejected, the file could not be + * read or written, its checksum did not match, the remote peer broke the + * protocol, or the data channel closed. + */ +public class TransferException extends WebRtcException { + + private static final long serialVersionUID = 1L; + + private final boolean resumable; + + + /** + * Creates the exception with a message that says what went wrong. + * + * @param message the detail message. + * @param resumable whether the transfer may be resumed. + */ + public TransferException(String message, boolean resumable) { + super(message); + this.resumable = resumable; + } + + /** + * Creates the exception with a message and the failure that caused it. + * + * @param message the detail message. + * @param cause the underlying failure. + * @param resumable whether the transfer may be resumed. + */ + public TransferException(String message, Throwable cause, boolean resumable) { + super(message, cause); + this.resumable = resumable; + } + + /** + * Tells whether the transfer stopped only because its data channel or + * {@link FileTransfers} closed. The sender may then resume it with {@link + * FileTransfers#resume(OutgoingTransfer)} over a new channel, and the + * receiver, unless {@link TransferOptions.Builder#resumable(boolean)} is + * off, keeps the data received so far for it. + * + * @return true when the transfer may be resumed. + */ + public boolean isResumable() { + return resumable; + } + +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferImpl.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferImpl.java new file mode 100644 index 000000000..9e15a47ba --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferImpl.java @@ -0,0 +1,173 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.client.transfer; + +import static java.util.Objects.requireNonNull; + +import java.io.IOException; +import java.nio.channels.FileChannel; +import java.nio.file.Path; +import java.security.MessageDigest; +import java.security.NoSuchAlgorithmException; +import java.util.List; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.CopyOnWriteArrayList; +import java.util.function.Consumer; + +import dev.onvoid.webrtc.client.Subscription; + +/** + * What both directions of a transfer share. The state is confined to the + * thread of the {@link FileTransfers}, except the progress and the done + * future, which may be read anywhere. + */ +abstract class TransferImpl implements Transfer { + + enum State { + /** Queued by the sender, or accepted and not yet begun by the receiver. */ + WAITING, + /** The sender offered it and waits for an answer. */ + OFFERED, + /** The SHA-256 of what was transferred before a resume is computed. */ + HASHING, + /** Data flows. */ + TRANSFERRING + } + + final FileTransfers owner; + + final String id; + + final String name; + + final long size; + + final Path path; + + final CompletableFuture done = new CompletableFuture<>(); + + final List> progressHandlers = new CopyOnWriteArrayList<>(); + + volatile TransferProgress progress; + + // Confined to the thread of the owner. + + State state = State.WAITING; + + FileChannel file; + + final MessageDigest digest; + + + TransferImpl(FileTransfers owner, String id, String name, long size, Path path) { + this.owner = owner; + this.id = id; + this.name = name; + this.size = size; + this.path = path; + this.progress = new TransferProgress(0, size); + + try { + this.digest = MessageDigest.getInstance("SHA-256"); + } + catch (NoSuchAlgorithmException e) { + // Every Java platform has SHA-256. + throw new IllegalStateException(e); + } + } + + @Override + public String id() { + return id; + } + + @Override + public String name() { + return name; + } + + @Override + public long size() { + return size; + } + + @Override + public Path file() { + return path; + } + + @Override + public TransferProgress progress() { + return progress; + } + + @Override + public Subscription onProgress(Consumer handler) { + requireNonNull(handler, "handler"); + + return owner.subscribe(this, handler); + } + + @Override + public CompletableFuture whenDone() { + return done.copy(); + } + + @Override + public void cancel() { + owner.cancel(this); + } + + boolean isDone() { + return done.isDone(); + } + + /** + * Ends the transfer, with a failure or, when the error is null, done. + * Runs on the owner's thread, or anywhere for a transfer the owner never + * took. + */ + void finish(TransferException error) { + closeFile(); + progressHandlers.clear(); + + if (error == null) { + done.complete(null); + } + else { + done.completeExceptionally(error); + } + } + + void closeFile() { + FileChannel open = file; + + if (open != null) { + try { + open.close(); + } + catch (IOException e) { + // Nothing left to lose. + } + } + } + + @Override + public String toString() { + return getClass().getSimpleName() + "[" + id + ", " + progress + "]"; + } +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferOffer.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferOffer.java new file mode 100644 index 000000000..641757806 --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferOffer.java @@ -0,0 +1,210 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.client.transfer; + +import static java.util.Objects.requireNonNull; + +import java.nio.file.Path; +import java.util.Locale; +import java.util.concurrent.atomic.AtomicBoolean; + +/** + * A file the remote peer wants to send, handed to {@link + * FileTransfers#onOffer}. It is accepted or rejected once; until then the + * sender waits, and sends nothing else. + *

+ * The name and the size come from the remote peer. The name may hold path + * separators, {@code ..} or characters a file system refuses, so it must not + * become a path as it is; {@link #safeFileName()} gives one that may. + */ +public final class TransferOffer { + + private static final int MAX_FILE_NAME = 200; + + private final FileTransfers owner; + + private final String id; + + private final String name; + + private final long size; + + private final AtomicBoolean decided = new AtomicBoolean(); + + + TransferOffer(FileTransfers owner, String id, String name, long size) { + this.owner = owner; + this.id = id; + this.name = name; + this.size = size; + } + + /** + * @return the id of the transfer. An offer that resumes a transfer has + * the id of the one it resumes. + */ + public String id() { + return id; + } + + /** + * @return the name the sender gave the file, as it sent it. + */ + public String name() { + return name; + } + + /** + * @return the size of the file in bytes, as the sender announced it. + * More is never accepted. + */ + public long size() { + return size; + } + + /** + * Makes the sender's name usable as a single file name: it keeps the + * part after the last {@code /} or {@code \}, replaces control, + * formatting and reserved characters and a leading dot with {@code _}, + * drops trailing dots and spaces, prefixes Windows device names such as + * {@code CON} with {@code _}, and cuts it to 200 characters. A name with + * nothing left becomes {@code file}. + *

{@code
+	 * offer.accept(downloads.resolve(offer.safeFileName()));
+	 * }
+ * + * @return a name that stays in the directory it is resolved against. + */ + public String safeFileName() { + return safeFileName(name); + } + + /** + * Accepts the file. Its data goes to {@link + * IncomingTransfer#partialFile()}, which replaces the target, if it + * exists, once the checksum matched. A partial file the same transfer + * left behind before is continued. + * + * @param target the file to write, chosen by the application. + * + * @return the transfer. + * + * @throws IllegalStateException if the offer was accepted or rejected + * before. + */ + public IncomingTransfer accept(Path target) { + requireNonNull(target, "target"); + + if (target.getFileName() == null) { + throw new IllegalArgumentException("The target " + target + " names no file"); + } + + decide(); + + return owner.accept(this, target); + } + + /** + * Rejects the file. The sender's transfer fails with the reason, and its + * next file follows. + * + * @param reason what the sender is told, at most 1024 bytes of UTF-8 of + * it. + * + * @throws IllegalStateException if the offer was accepted or rejected + * before. + */ + public void reject(String reason) { + requireNonNull(reason, "reason"); + decide(); + + owner.reject(this, reason); + } + + /** + * Returns the offer's id, size and the length of its name, without the + * name itself, which the remote peer chose. + */ + @Override + public String toString() { + return "TransferOffer[id=" + id + ", size=" + size + ", name length=" + name.length() + "]"; + } + + boolean isDecided() { + return decided.get(); + } + + private void decide() { + if (!decided.compareAndSet(false, true)) { + throw new IllegalStateException("The offer " + id + " was already accepted or rejected"); + } + } + + static String safeFileName(String name) { + String base = name.substring(Math.max(name.lastIndexOf('/'), name.lastIndexOf('\\')) + 1); + StringBuilder safe = new StringBuilder(Math.min(base.length(), MAX_FILE_NAME)); + + for (int i = 0; i < base.length() && safe.length() < MAX_FILE_NAME; ) { + int c = base.codePointAt(i); + i += Character.charCount(c); + + boolean replace = Character.isISOControl(c) + || Character.getType(c) == Character.FORMAT + || Character.getType(c) == Character.LINE_SEPARATOR + || Character.getType(c) == Character.PARAGRAPH_SEPARATOR + || Character.getType(c) == Character.SURROGATE + || Character.getType(c) == Character.UNASSIGNED + || "<>:\"|?*".indexOf(c) >= 0 + || (c == '.' && safe.length() == 0); + + if (replace) { + safe.append('_'); + } + else if (safe.length() + Character.charCount(c) <= MAX_FILE_NAME) { + safe.appendCodePoint(c); + } + else { + break; + } + } + + int end = safe.length(); + + while (end > 0 && (safe.charAt(end - 1) == '.' || safe.charAt(end - 1) == ' ')) { + end--; + } + safe.setLength(end); + + while (safe.length() > 0 && safe.charAt(0) == ' ') { + safe.deleteCharAt(0); + } + + if (safe.length() == 0) { + return "file"; + } + + String stem = safe.toString(); + int dot = stem.indexOf('.'); + String device = (dot < 0 ? stem : stem.substring(0, dot)).trim().toUpperCase(Locale.ROOT); + + if (device.matches("CON|PRN|AUX|NUL|COM[0-9¹²³]|LPT[0-9¹²³]|CONIN\\$|CONOUT\\$")) { + stem = "_" + stem; + } + + return stem; + } +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferOptions.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferOptions.java new file mode 100644 index 000000000..b61603cdc --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferOptions.java @@ -0,0 +1,143 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.client.transfer; + +/** + * How {@link FileTransfers} sends and receives. + *
{@code
+ * TransferOptions.builder().window(8 * 1024 * 1024).build();
+ * }
+ */ +public final class TransferOptions { + + /** The largest chunk, so that a DATA frame fits in 256 KiB, WebRTC's message size limit. */ + static final int MAX_CHUNK_SIZE = 256 * 1024 - Frames.DATA_HEADER; + + static final int MIN_CHUNK_SIZE = 1024; + + static final int MAX_WINDOW = 64 * 1024 * 1024; + + private static final TransferOptions DEFAULTS = builder().build(); + + final int chunkSize; + + final int window; + + final boolean resumable; + + + private TransferOptions(Builder builder) { + this.chunkSize = builder.chunkSize; + this.window = builder.window; + this.resumable = builder.resumable; + } + + /** + * @return the default options. + */ + public static TransferOptions defaults() { + return DEFAULTS; + } + + /** + * @return a builder with the default options. + */ + public static Builder builder() { + return new Builder(); + } + + + + /** Builds {@link TransferOptions}. */ + public static final class Builder { + + private int chunkSize = 32 * 1024; + + private int window = 4 * 1024 * 1024; + + private boolean resumable = true; + + + private Builder() { + } + + /** + * Sets how much of a file one message carries. The default, 32 KiB, + * fits every WebRTC implementation. + * + * @param bytes from 1 KiB to 256 KiB less 25 bytes of header. + * + * @return this builder. + */ + public Builder chunkSize(int bytes) { + if (bytes < MIN_CHUNK_SIZE || bytes > MAX_CHUNK_SIZE) { + throw new IllegalArgumentException("The chunk size must be between " + MIN_CHUNK_SIZE + " and " + + MAX_CHUNK_SIZE + ", got " + bytes); + } + + this.chunkSize = bytes; + return this; + } + + /** + * Sets how many bytes of a file the remote peer may send before this + * side confirmed them, which bounds the memory received data takes + * while it waits to be written. A transfer moves at most a window per + * round trip, so 4 MiB, the default, carry 40 MiB/s at a round trip of + * 100 ms. + *

+ * Keep it below the peer's {@link + * dev.onvoid.webrtc.client.PeerOptions.Builder#channelReceiveLimit(long)}, + * 16 MiB by default, or a slow disk may make the channel close. + * + * @param bytes from 1 KiB to 64 MiB. + * + * @return this builder. + */ + public Builder window(int bytes) { + if (bytes < MIN_CHUNK_SIZE || bytes > MAX_WINDOW) { + throw new IllegalArgumentException("The window must be between " + MIN_CHUNK_SIZE + " and " + + MAX_WINDOW + ", got " + bytes); + } + + this.window = bytes; + return this; + } + + /** + * Sets whether a received file whose transfer was interrupted keeps + * its partial data, so that the sender can resume it. On by default. + * When off, the partial file is deleted on any failure and an old one + * is never continued. + * + * @param resumable false to start each transfer over. + * + * @return this builder. + */ + public Builder resumable(boolean resumable) { + this.resumable = resumable; + return this; + } + + /** + * @return the options. + */ + public TransferOptions build() { + return new TransferOptions(this); + } + } +} diff --git a/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferProgress.java b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferProgress.java new file mode 100644 index 000000000..337433a58 --- /dev/null +++ b/webrtc/src/main/java/dev/onvoid/webrtc/client/transfer/TransferProgress.java @@ -0,0 +1,61 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.client.transfer; + +/** + * How far a {@link Transfer} got: the bytes the receiver wrote to its file and + * confirmed. The sender learns of them with the receiver's acknowledgements, + * not when it hands data to the transport. + */ +public final class TransferProgress { + + private final long bytes; + + private final long size; + + + TransferProgress(long bytes, long size) { + this.bytes = bytes; + this.size = size; + } + + /** + * @return the bytes confirmed so far. + */ + public long bytes() { + return bytes; + } + + /** + * @return the size of the file. + */ + public long size() { + return size; + } + + /** + * @return the share confirmed, from 0 to 1; 1 for an empty file. + */ + public double fraction() { + return size == 0 ? 1 : (double) bytes / size; + } + + @Override + public String toString() { + return "TransferProgress[" + bytes + " of " + size + " bytes]"; + } +} diff --git a/webrtc/src/main/java/module-info.java b/webrtc/src/main/java/module-info.java index 8a613027c..a087f4f97 100644 --- a/webrtc/src/main/java/module-info.java +++ b/webrtc/src/main/java/module-info.java @@ -7,6 +7,7 @@ exports dev.onvoid.webrtc; exports dev.onvoid.webrtc.client; + exports dev.onvoid.webrtc.client.transfer; exports dev.onvoid.webrtc.logging; exports dev.onvoid.webrtc.media; exports dev.onvoid.webrtc.media.audio; diff --git a/webrtc/src/test/java/dev/onvoid/webrtc/client/FileTransferTests.java b/webrtc/src/test/java/dev/onvoid/webrtc/client/FileTransferTests.java new file mode 100644 index 000000000..bbec05236 --- /dev/null +++ b/webrtc/src/test/java/dev/onvoid/webrtc/client/FileTransferTests.java @@ -0,0 +1,69 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.client; + +import static org.junit.jupiter.api.Assertions.assertArrayEquals; +import static org.junit.jupiter.api.Assertions.assertEquals; + +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.Random; +import java.util.concurrent.CompletableFuture; + +import dev.onvoid.webrtc.client.transfer.FileTransfers; +import dev.onvoid.webrtc.client.transfer.IncomingTransfer; +import dev.onvoid.webrtc.client.transfer.OutgoingTransfer; + +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; + +/** + * File transfers over a data channel between two real peers. + */ +class FileTransferTests extends ClientTestBase { + + @TempDir + Path dir; + + + @Test + void sendsFileBetweenPeers() throws Exception { + Peer[] peers = pair(); + CompletableFuture incoming = new CompletableFuture<>(); + + peers[1].onChannel(channel -> FileTransfers.over(channel) + .onOffer(offer -> incoming.complete(offer.accept(dir.resolve(offer.safeFileName() + ".out"))))); + + byte[] data = new byte[5 * 1024 * 1024 + 17]; + new Random(1).nextBytes(data); + Path source = Files.write(dir.resolve("video.bin"), data); + + FileTransfers sender = FileTransfers.over(peers[0].createChannel("files")); + OutgoingTransfer outgoing = sender.send(source); + + await(outgoing.whenDone()); + IncomingTransfer received = await(incoming); + await(received.whenDone()); + + assertEquals(dir.resolve("video.bin.out"), received.file()); + assertArrayEquals(data, Files.readAllBytes(received.file())); + assertEquals(data.length, outgoing.progress().bytes()); + + sender.close(); + await(sender.whenClosed()); + } +} diff --git a/webrtc/src/test/java/dev/onvoid/webrtc/client/LoopbackChannel.java b/webrtc/src/test/java/dev/onvoid/webrtc/client/LoopbackChannel.java new file mode 100644 index 000000000..ee2bfb300 --- /dev/null +++ b/webrtc/src/test/java/dev/onvoid/webrtc/client/LoopbackChannel.java @@ -0,0 +1,240 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.client; + +import java.nio.ByteBuffer; +import java.nio.charset.StandardCharsets; +import java.util.ArrayDeque; +import java.util.ArrayList; +import java.util.List; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Executors; +import java.util.concurrent.atomic.AtomicLong; +import java.util.function.Consumer; +import java.util.function.UnaryOperator; + +/** + * One end of an in-memory data channel, for tests of what is built on {@link + * DataChannel} without native code. Each end has an event thread of its own, + * where its handlers run and its send futures complete, and delivers in + * order. Messages that arrive without a handler are kept for the next one. + */ +public final class LoopbackChannel implements DataChannel { + + private final String label; + + /** Shared by both ends, so that a send and a close of either never interleave. */ + private final Object lock; + + private final ExecutorService events; + + private LoopbackChannel remote; + + private volatile ChannelState state = ChannelState.OPEN; + + private volatile UnaryOperator outbound = UnaryOperator.identity(); + + /** Binary bytes this end sent, before the interceptor. */ + public final AtomicLong sentBytes = new AtomicLong(); + + // Confined to the event thread. + + private final List> messageHandlers = new ArrayList<>(); + + private final List> stateHandlers = new ArrayList<>(); + + private final ArrayDeque early = new ArrayDeque<>(); + + + private LoopbackChannel(String label, String side, Object lock) { + this.label = label; + this.lock = lock; + this.events = Executors.newSingleThreadExecutor(task -> { + Thread thread = new Thread(task, "loopback-" + label + "-" + side); + thread.setDaemon(true); + return thread; + }); + } + + /** + * @return two open ends of a channel. + */ + public static LoopbackChannel[] pair(String label) { + Object lock = new Object(); + LoopbackChannel first = new LoopbackChannel(label, "first", lock); + LoopbackChannel second = new LoopbackChannel(label, "second", lock); + first.remote = second; + second.remote = first; + return new LoopbackChannel[] { first, second }; + } + + /** + * Passes each binary message this end sends through the interceptor, on + * the sending thread; a null result drops the message. + */ + public void intercept(UnaryOperator interceptor) { + this.outbound = interceptor; + } + + @Override + public String label() { + return label; + } + + @Override + public ChannelState state() { + return state; + } + + @Override + public CompletableFuture whenOpen() { + return CompletableFuture.completedFuture(this); + } + + @Override + public CompletableFuture send(String text) { + return deliver(text.getBytes(StandardCharsets.UTF_8), false); + } + + @Override + public CompletableFuture send(byte[] data) { + return deliver(data.clone(), true); + } + + @Override + public CompletableFuture send(ByteBuffer data) { + byte[] copy = new byte[data.remaining()]; + data.duplicate().get(copy); + return deliver(copy, true); + } + + @Override + public long bufferedAmount() { + return 0; + } + + @Override + public Subscription onMessage(Consumer handler) { + run(() -> { + messageHandlers.add(handler); + + while (!early.isEmpty()) { + handler.accept(early.poll()); + } + }, () -> {}); + + return () -> run(() -> messageHandlers.remove(handler), () -> {}); + } + + @Override + public Subscription onStateChange(Consumer handler) { + run(() -> { + handler.accept(state); + stateHandlers.add(handler); + }, () -> handler.accept(ChannelState.CLOSED)); + + return () -> run(() -> stateHandlers.remove(handler), () -> {}); + } + + /** Closes both ends. */ + @Override + public void close() { + synchronized (lock) { + closeHere(); + remote.closeHere(); + } + } + + private void run(Runnable task, Runnable closed) { + synchronized (lock) { + if (events.isShutdown()) { + closed.run(); + } + else { + events.execute(task); + } + } + } + + private void closeHere() { + if (state == ChannelState.CLOSED) { + return; + } + + state = ChannelState.CLOSED; + + events.execute(() -> { + for (Consumer handler : new ArrayList<>(stateHandlers)) { + handler.accept(ChannelState.CLOSED); + } + + messageHandlers.clear(); + stateHandlers.clear(); + early.clear(); + }); + events.shutdown(); + } + + private CompletableFuture deliver(byte[] data, boolean binary) { + CompletableFuture sent = new CompletableFuture<>(); + + synchronized (lock) { + if (state != ChannelState.OPEN) { + sent.completeExceptionally(new PeerClosedException("The data channel " + label + " is closed")); + return sent; + } + + byte[] out = data; + + if (binary) { + sentBytes.addAndGet(data.length); + out = outbound.apply(data); + } + + if (out != null && state == ChannelState.OPEN) { + remote.receive(new Message(out, binary)); + } + + if (state == ChannelState.OPEN) { + events.execute(() -> sent.complete(null)); + } + else { + sent.completeExceptionally(new PeerClosedException("The data channel " + label + " closed")); + } + } + + return sent; + } + + private void receive(Message message) { + if (state != ChannelState.OPEN) { + return; + } + + events.execute(() -> { + if (messageHandlers.isEmpty()) { + early.add(message); + return; + } + + for (Consumer handler : new ArrayList<>(messageHandlers)) { + handler.accept(message); + } + }); + } +} diff --git a/webrtc/src/test/java/dev/onvoid/webrtc/client/transfer/FileTransfersTests.java b/webrtc/src/test/java/dev/onvoid/webrtc/client/transfer/FileTransfersTests.java new file mode 100644 index 000000000..c4958c0ee --- /dev/null +++ b/webrtc/src/test/java/dev/onvoid/webrtc/client/transfer/FileTransfersTests.java @@ -0,0 +1,552 @@ +/* + * Copyright 2026 Alex Andres + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package dev.onvoid.webrtc.client.transfer; + +import static org.junit.jupiter.api.Assertions.assertArrayEquals; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.ArrayList; +import java.util.List; +import java.util.Random; +import java.util.concurrent.BlockingQueue; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.CopyOnWriteArrayList; +import java.util.concurrent.ExecutionException; +import java.util.concurrent.LinkedBlockingQueue; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicBoolean; +import java.util.concurrent.atomic.AtomicLong; + +import dev.onvoid.webrtc.client.LoopbackChannel; + +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; + +/** + * The transfer protocol over an in-memory channel, with no native code. + */ +class FileTransfersTests { + + private static final long TIMEOUT_SECONDS = 15; + + /** Small, so that a transfer takes many chunks and acknowledgements. */ + private static final TransferOptions SMALL = TransferOptions.builder() + .chunkSize(16 * 1024) + .window(64 * 1024) + .build(); + + @TempDir + Path dir; + + private final List opened = new ArrayList<>(); + + + @AfterEach + void closeTransfers() { + opened.forEach(FileTransfers::close); + } + + @Test + void sendsFile() throws Exception { + LoopbackChannel[] channels = LoopbackChannel.pair("files"); + FileTransfers sender = open(channels[0], SMALL); + FileTransfers receiver = open(channels[1], SMALL); + + Path source = randomFile("source.bin", 1024 * 1024 + 123); + Path target = dir.resolve("target.bin"); + CompletableFuture incoming = acceptInto(receiver, target); + + OutgoingTransfer outgoing = sender.send(source); + List progress = new CopyOnWriteArrayList<>(); + outgoing.onProgress(p -> progress.add(p.bytes())); + + await(outgoing.whenDone()); + IncomingTransfer received = await(incoming); + await(received.whenDone()); + + assertArrayEquals(Files.readAllBytes(source), Files.readAllBytes(target)); + assertEquals(outgoing.id(), received.id()); + assertEquals("source.bin", received.name()); + assertEquals(Files.size(source), received.progress().bytes()); + assertEquals(Files.size(source), outgoing.progress().bytes()); + assertFalse(Files.exists(received.partialFile())); + + // Confirmed a quarter window at a time, never going back. + assertTrue(progress.size() > 10, () -> "Progress: " + progress); + for (int i = 1; i < progress.size(); i++) { + assertTrue(progress.get(i) >= progress.get(i - 1), () -> "Progress: " + progress); + } + } + + @Test + void sendsEmptyFile() throws Exception { + LoopbackChannel[] channels = LoopbackChannel.pair("files"); + FileTransfers sender = open(channels[0]); + FileTransfers receiver = open(channels[1]); + + Path target = dir.resolve("empty.out"); + CompletableFuture incoming = acceptInto(receiver, target); + + await(sender.send(Files.createFile(dir.resolve("empty"))).whenDone()); + await(await(incoming).whenDone()); + + assertEquals(0, Files.size(target)); + assertEquals(1, await(incoming).progress().fraction()); + } + + @Test + void bothDirectionsAtOnce() throws Exception { + LoopbackChannel[] channels = LoopbackChannel.pair("files"); + FileTransfers first = open(channels[0]); + FileTransfers second = open(channels[1]); + + Path one = randomFile("one", 300 * 1024); + Path two = randomFile("two", 200 * 1024); + CompletableFuture toSecond = acceptInto(second, dir.resolve("one.out")); + CompletableFuture toFirst = acceptInto(first, dir.resolve("two.out")); + + CompletableFuture sentOne = first.send(one).whenDone(); + CompletableFuture sentTwo = second.send(two).whenDone(); + + await(sentOne); + await(sentTwo); + await(await(toSecond).whenDone()); + await(await(toFirst).whenDone()); + + assertArrayEquals(Files.readAllBytes(one), Files.readAllBytes(dir.resolve("one.out"))); + assertArrayEquals(Files.readAllBytes(two), Files.readAllBytes(dir.resolve("two.out"))); + } + + @Test + void filesGoInOrder() throws Exception { + LoopbackChannel[] channels = LoopbackChannel.pair("files"); + FileTransfers sender = open(channels[0]); + FileTransfers receiver = open(channels[1]); + + OutgoingTransfer[] sent = new OutgoingTransfer[2]; + List offered = new CopyOnWriteArrayList<>(); + List previousDone = new CopyOnWriteArrayList<>(); + + receiver.onOffer(offer -> { + offered.add(offer.name()); + previousDone.add(offered.size() == 1 || sent[0].whenDone().isDone()); + offer.accept(dir.resolve(offer.safeFileName() + ".out")); + }); + + sent[0] = sender.send(randomFile("a", 100 * 1024)); + sent[1] = sender.send(randomFile("b", 100 * 1024)); + + await(sent[1].whenDone()); + + assertEquals(List.of("a", "b"), offered); + assertEquals(List.of(true, true), previousDone); + } + + @Test + void offerWaitsForHandler() throws Exception { + LoopbackChannel[] channels = LoopbackChannel.pair("files"); + FileTransfers sender = open(channels[0]); + FileTransfers receiver = open(channels[1]); + + CompletableFuture offered = waitForOffered(channels[0]); + OutgoingTransfer outgoing = sender.send(randomFile("late", 1000)); + await(offered); + + // The handler comes after the offer. + acceptInto(receiver, dir.resolve("late.out")); + + await(outgoing.whenDone()); + } + + @Test + void rejectFailsSender() throws Exception { + LoopbackChannel[] channels = LoopbackChannel.pair("files"); + FileTransfers sender = open(channels[0]); + FileTransfers receiver = open(channels[1]); + + receiver.onOffer(offer -> offer.reject("too large")); + + OutgoingTransfer rejected = sender.send(randomFile("big", 1000)); + TransferException error = failure(rejected.whenDone()); + + assertTrue(error.getMessage().contains("too large"), error::getMessage); + assertFalse(error.isResumable()); + assertThrows(IllegalStateException.class, () -> sender.resume(rejected)); + } + + @Test + void senderCancels() throws Exception { + LoopbackChannel[] channels = LoopbackChannel.pair("files"); + FileTransfers sender = open(channels[0], SMALL); + FileTransfers receiver = open(channels[1], SMALL); + + // Without acknowledgements, the sender stops after a window. + channels[1].intercept(frame -> frame[0] == Frames.ACK ? null : frame); + + Path target = dir.resolve("cancelled.out"); + CompletableFuture incoming = acceptInto(receiver, target); + OutgoingTransfer outgoing = sender.send(randomFile("cancelled", 1024 * 1024)); + IncomingTransfer received = await(incoming); + await(reached(received, 64 * 1024)); + + outgoing.cancel(); + + assertInstanceOf(TransferCancelledException.class, failure(outgoing.whenDone())); + TransferException error = failure(received.whenDone()); + assertInstanceOf(TransferCancelledException.class, error); + assertTrue(error.getMessage().contains("remote peer cancelled"), error::getMessage); + assertFalse(Files.exists(received.partialFile())); + assertFalse(Files.exists(target)); + assertThrows(IllegalStateException.class, () -> sender.resume(outgoing)); + } + + @Test + void receiverCancels() throws Exception { + LoopbackChannel[] channels = LoopbackChannel.pair("files"); + FileTransfers sender = open(channels[0], SMALL); + FileTransfers receiver = open(channels[1], SMALL); + + channels[1].intercept(frame -> frame[0] == Frames.ACK ? null : frame); + + CompletableFuture incoming = acceptInto(receiver, dir.resolve("cancelled.out")); + OutgoingTransfer outgoing = sender.send(randomFile("cancelled", 1024 * 1024)); + IncomingTransfer received = await(incoming); + await(reached(received, 64 * 1024)); + + channels[1].intercept(frame -> frame); + received.cancel(); + + assertInstanceOf(TransferCancelledException.class, failure(received.whenDone())); + assertInstanceOf(TransferCancelledException.class, failure(outgoing.whenDone())); + assertFalse(Files.exists(received.partialFile())); + + // The channel goes on. + CompletableFuture next = acceptInto(receiver, dir.resolve("next.out")); + await(sender.send(randomFile("next", 1000)).whenDone()); + await(await(next).whenDone()); + } + + @Test + void corruptionDetected() throws Exception { + LoopbackChannel[] channels = LoopbackChannel.pair("files"); + FileTransfers sender = open(channels[0], SMALL); + FileTransfers receiver = open(channels[1], SMALL); + + AtomicLong frames = new AtomicLong(); + channels[0].intercept(frame -> { + if (frame[0] == Frames.DATA && frames.incrementAndGet() == 3) { + frame[Frames.DATA_HEADER + 100] ^= 1; + } + return frame; + }); + + Path target = dir.resolve("corrupt.out"); + CompletableFuture incoming = acceptInto(receiver, target); + OutgoingTransfer outgoing = sender.send(randomFile("corrupt", 200 * 1024)); + + TransferException error = failure(outgoing.whenDone()); + assertTrue(error.getMessage().contains("SHA-256"), error::getMessage); + assertFalse(error instanceof TransferCancelledException); + + IncomingTransfer received = await(incoming); + assertTrue(failure(received.whenDone()).getMessage().contains("SHA-256")); + assertFalse(Files.exists(target)); + assertFalse(Files.exists(received.partialFile())); + } + + @Test + void resumesOverNewChannel() throws Exception { + LoopbackChannel[] first = LoopbackChannel.pair("files"); + FileTransfers sender = open(first[0], SMALL); + FileTransfers receiver = open(first[1], SMALL); + + // The connection breaks after 300 KiB of data. + AtomicLong data = new AtomicLong(); + first[0].intercept(frame -> { + if (frame[0] == Frames.DATA && data.addAndGet(frame.length - Frames.DATA_HEADER) > 300 * 1024) { + first[0].close(); + return null; + } + return frame; + }); + + Path source = randomFile("resumed", 1024 * 1024); + Path target = dir.resolve("resumed.out"); + CompletableFuture incoming = acceptInto(receiver, target); + OutgoingTransfer interrupted = sender.send(source); + IncomingTransfer partial = await(incoming); + + assertTrue(failure(interrupted.whenDone()).isResumable()); + assertTrue(failure(partial.whenDone()).isResumable()); + await(sender.whenClosed()); + + long kept = Files.size(partial.partialFile()); + assertTrue(kept > 200 * 1024 && kept <= 300 * 1024, () -> "Kept " + kept); + + LoopbackChannel[] second = LoopbackChannel.pair("files"); + FileTransfers newSender = open(second[0], SMALL); + FileTransfers newReceiver = open(second[1], SMALL); + + CompletableFuture resumedIncoming = acceptInto(newReceiver, target); + OutgoingTransfer resumed = newSender.resume(interrupted); + List progress = new CopyOnWriteArrayList<>(); + resumed.onProgress(p -> progress.add(p.bytes())); + + await(resumed.whenDone()); + await(await(resumedIncoming).whenDone()); + + assertEquals(interrupted.id(), resumed.id()); + assertArrayEquals(Files.readAllBytes(source), Files.readAllBytes(target)); + assertFalse(Files.exists(partial.partialFile())); + // Only what was missing went over the new channel. + assertTrue(second[0].sentBytes.get() < Files.size(source) - kept + 64 * 1024, + () -> "Sent " + second[0].sentBytes.get()); + // Progress goes on from where the first channel stopped. + assertTrue(progress.contains(kept), () -> "Progress: " + progress); + assertTrue(progress.stream().allMatch(bytes -> bytes == 0 || bytes >= kept), () -> "Progress: " + progress); + } + + @Test + void notResumableStartsOver() throws Exception { + TransferOptions options = TransferOptions.builder().resumable(false).build(); + LoopbackChannel[] channels = LoopbackChannel.pair("files"); + FileTransfers sender = open(channels[0], options); + FileTransfers receiver = open(channels[1], options); + + Path source = randomFile("fresh", 50 * 1024); + Path target = dir.resolve("fresh.out"); + CompletableFuture incoming = acceptInto(receiver, target); + OutgoingTransfer outgoing = sender.send(source); + + // A partial file of the same transfer, from before, is not continued. + Files.write(dir.resolve("fresh.out." + outgoing.id().substring(0, 16) + ".part"), new byte[10 * 1024]); + + await(outgoing.whenDone()); + await(await(incoming).whenDone()); + assertArrayEquals(Files.readAllBytes(source), Files.readAllBytes(target)); + } + + @Test + void closeFailsResumable() throws Exception { + LoopbackChannel[] channels = LoopbackChannel.pair("files"); + FileTransfers sender = open(channels[0]); + open(channels[1]); + + CompletableFuture sentOffer = waitForOffered(channels[0]); + OutgoingTransfer offered = sender.send(randomFile("offered", 1000)); + await(sentOffer); + + sender.close(); + + assertTrue(failure(offered.whenDone()).isResumable()); + await(sender.whenClosed()); + assertTrue(failure(sender.send(randomFile("after", 10)).whenDone()).isResumable()); + } + + @Test + void windowEnforced() throws Exception { + LoopbackChannel[] channels = LoopbackChannel.pair("files"); + BlockingQueue frames = rawPeer(channels[0]); + FileTransfers receiver = open(channels[1], TransferOptions.builder().window(16 * 1024).build()); + + CompletableFuture incoming = acceptInto(receiver, dir.resolve("flood.out")); + String id = "00112233445566778899aabbccddeeff"; + channels[0].send(Frames.offer(id, 1024 * 1024, "flood")); + + Frames.Frame accept = Frames.decode(poll(frames)); + assertEquals(Frames.ACCEPT, accept.type); + assertEquals(16 * 1024, accept.window); + + // More than the window, with no acknowledgement awaited. + channels[0].send(Frames.data(id, 0, 20 * 1024)); + + Frames.Frame cancel = Frames.decode(poll(frames)); + assertEquals(Frames.CANCEL, cancel.type); + assertTrue(cancel.failed); + assertTrue(cancel.text.contains("window"), cancel.text); + + TransferException error = failure(await(incoming).whenDone()); + assertFalse(error.isResumable()); + assertTrue(failure(receiver.whenClosed()).getMessage().contains("broke the file transfer protocol")); + assertFalse(Files.exists(await(incoming).partialFile())); + } + + @Test + void announcedSizeEnforced() throws Exception { + LoopbackChannel[] channels = LoopbackChannel.pair("files"); + BlockingQueue frames = rawPeer(channels[0]); + FileTransfers receiver = open(channels[1]); + + CompletableFuture incoming = acceptInto(receiver, dir.resolve("small.out")); + String id = "ffeeddccbbaa99887766554433221100"; + channels[0].send(Frames.offer(id, 100, "small")); + + assertEquals(Frames.ACCEPT, Frames.decode(poll(frames)).type); + + channels[0].send(Frames.data(id, 0, 101)); + + Frames.Frame cancel = Frames.decode(poll(frames)); + assertEquals(Frames.CANCEL, cancel.type); + assertTrue(cancel.text.contains("100 bytes offered"), cancel.text); + assertFalse(failure(await(incoming).whenDone()).isResumable()); + } + + @Test + void textMessageClosesChannel() throws Exception { + LoopbackChannel[] channels = LoopbackChannel.pair("files"); + FileTransfers receiver = open(channels[1]); + + channels[0].send("hello"); + + assertTrue(failure(receiver.whenClosed()).getMessage().contains("text message")); + } + + @Test + void sendRefusesDirectory() { + LoopbackChannel[] channels = LoopbackChannel.pair("files"); + FileTransfers sender = open(channels[0]); + + assertThrows(IOException.class, () -> sender.send(dir)); + assertThrows(IOException.class, () -> sender.send(dir.resolve("missing"))); + assertThrows(IllegalArgumentException.class, () -> sender.send(dir, "x".repeat(1025))); + } + + @Test + void framesRoundTrip() throws Exception { + String id = "0123456789abcdef0123456789abcdef"; + + Frames.Frame offer = Frames.decode(Frames.offer(id, 1L << 40, "Bericht ü.pdf")); + assertEquals(Frames.OFFER, offer.type); + assertEquals(id, offer.id); + assertEquals(1L << 40, offer.value); + assertEquals("Bericht ü.pdf", offer.text); + + Frames.Frame cancel = Frames.decode(Frames.cancel(id, true, "ä".repeat(600))); + assertTrue(cancel.failed); + assertEquals(512, cancel.text.length()); + + byte[] data = Frames.data(id, 7, 3); + data[Frames.DATA_HEADER] = 42; + Frames.Frame chunk = Frames.decode(data); + assertEquals(7, chunk.value); + assertEquals(3, chunk.payloadLength); + assertEquals(42, chunk.payload[chunk.payloadOffset]); + + byte[] ack = Frames.ack(id, 5); + assertThrows(java.net.ProtocolException.class, () -> Frames.decode(java.util.Arrays.copyOf(ack, ack.length - 1))); + assertThrows(java.net.ProtocolException.class, () -> Frames.decode(java.util.Arrays.copyOf(ack, ack.length + 1))); + assertThrows(java.net.ProtocolException.class, () -> Frames.decode(new byte[] { 99 })); + } + + @Test + void safeFileNames() { + assertEquals("passwd", TransferOffer.safeFileName("../../etc/passwd")); + assertEquals("evil.exe", TransferOffer.safeFileName("C:\\Windows\\evil.exe")); + assertEquals("_bashrc", TransferOffer.safeFileName(".bashrc")); + assertEquals("_", TransferOffer.safeFileName("..")); + assertEquals("file", TransferOffer.safeFileName("")); + assertEquals("file", TransferOffer.safeFileName("dir/")); + assertEquals("a_b_c", TransferOffer.safeFileName("a:b\u0000c")); + assertEquals("report_fdp.exe", TransferOffer.safeFileName("report\u202Efdp.exe")); + assertEquals("_CON.txt", TransferOffer.safeFileName("CON.txt")); + assertEquals("_nul", TransferOffer.safeFileName("nul")); + assertEquals("name", TransferOffer.safeFileName("name. . ")); + assertEquals("Bericht ü.pdf", TransferOffer.safeFileName("Bericht ü.pdf")); + assertEquals(200, TransferOffer.safeFileName("x".repeat(300)).length()); + } + + private FileTransfers open(LoopbackChannel channel) { + return open(channel, TransferOptions.defaults()); + } + + private FileTransfers open(LoopbackChannel channel, TransferOptions options) { + FileTransfers transfers = FileTransfers.over(channel, options); + opened.add(transfers); + return transfers; + } + + private Path randomFile(String name, int size) throws IOException { + byte[] data = new byte[size]; + new Random(size).nextBytes(data); + return Files.write(dir.resolve(name), data); + } + + /** Accepts the next offer, and only that one. */ + private static CompletableFuture acceptInto(FileTransfers receiver, Path target) { + CompletableFuture accepted = new CompletableFuture<>(); + AtomicBoolean taken = new AtomicBoolean(); + receiver.onOffer(offer -> { + if (taken.compareAndSet(false, true)) { + accepted.complete(offer.accept(target)); + } + }); + return accepted; + } + + /** Completes once the end sent an offer. */ + private static CompletableFuture waitForOffered(LoopbackChannel end) { + CompletableFuture offered = new CompletableFuture<>(); + end.intercept(frame -> { + if (frame[0] == Frames.OFFER) { + offered.complete(null); + } + return frame; + }); + return offered; + } + + private static CompletableFuture reached(Transfer transfer, long bytes) { + CompletableFuture reached = new CompletableFuture<>(); + transfer.onProgress(p -> { + if (p.bytes() >= bytes) { + reached.complete(null); + } + }); + return reached; + } + + /** Collects what reaches an end that speaks the protocol by hand. */ + private static BlockingQueue rawPeer(LoopbackChannel end) { + BlockingQueue frames = new LinkedBlockingQueue<>(); + end.onMessage(message -> frames.add(message.bytes())); + return frames; + } + + private static byte[] poll(BlockingQueue frames) throws InterruptedException { + byte[] frame = frames.poll(TIMEOUT_SECONDS, TimeUnit.SECONDS); + assertTrue(frame != null, "No frame arrived"); + return frame; + } + + private static T await(CompletableFuture future) throws Exception { + return future.get(TIMEOUT_SECONDS, TimeUnit.SECONDS); + } + + private static TransferException failure(CompletableFuture future) throws Exception { + ExecutionException error = assertThrows(ExecutionException.class, + () -> future.get(TIMEOUT_SECONDS, TimeUnit.SECONDS)); + return assertInstanceOf(TransferException.class, error.getCause()); + } +}