Send Session: Outgoing Transfer Orchestration

Chapter V

This module traces a single outgoing transfer from SendNotifier.startSession() — which registers device info and negotiates prepare-upload with the target, including PIN retry — through the per-file isolate dispatch that streams bytes via HttpUploadService.postStream(). It highlights the two distinct Rust bridges the Dart app leans on: the FRB-generated RsHttpClient for control-plane calls, and the rhttp package's Rust client for the actual cert-pinned HTTPS byte stream. Understanding this hand-off is key to seeing where pure-Dart orchestration ends and the native TLS/cert-pinning core takes over.

From SendNotifier to the Rust HTTP core

SendNotifier.startSession()…ovider/network/send_provider.dart

RsHttpClient (FRB bridge)app/rust/src/api/http.rs

Upload isolate handler…isolate/child/upload_isolate.dart

core::LsHttpClientV2core/src/http/client/v2.rs

RhttpWrapper.postStream()app/lib/util/rhttp.dart

rhttp native client (TLS)app/lib/util/rhttp.dart

Figure I · Click a node to see what it does, where it lives in the code, and its labeled connections — the annotation opens beside it.

walkthrough

Handing bytes off to the native HTTP client

common/lib/src/task/upload/http_upload.dart · lines 16–42

lines 16–26

upload() takes the raw byte stream plus everything needed to address the request: the target device, the remote session/file identifiers, the per-file upload token, and progress/cancel hooks passed down from the isolate.

lines 27–36

It calls _client.postStream() — the CustomHttpClient abstraction — building the /upload URL via ApiRoute and passing sessionId/fileId/token as query params plus Content-Length/Content-Type headers.

lines 37–42

The actual byte stream, progress callback, and cancel token are handed straight through — this is the exact point where pure-Dart orchestration hands off to whatever concrete client implements postStream (RhttpWrapper, backed by Rust).

16  Future<void> upload({17    required Stream<List<int>> stream,18    required int contentLength,19    required String contentType,20    required Device target,21    required String? remoteSessionId,22    required String fileId,23    required String token,24    required void Function(double) onSendProgress,25    required CustomCancelToken cancelToken,26  }) async {27    await _client.postStream(28      uri: ApiRoute.upload.target(target),29      query: {30        if (remoteSessionId != null) 'sessionId': remoteSessionId,31        'fileId': fileId,32        'token': token,33      },34      headers: {35        'Content-Length': contentLength.toString(),36        'Content-Type': contentType,37      },38      stream: stream,39      onSendProgress: onSendProgress,40      cancelToken: cancelToken,41    );42  }

step 1 of 3

70RhttpClient createRhttpClient(Duration timeout, StoredSecurityContext securityContext, {Interceptor? interceptor}) {71  return RhttpClient.createSync(72    settings: ClientSettings(73      timeoutSettings: TimeoutSettings(74        timeout: timeout,75      ),76      tlsSettings: TlsSettings(77        verifyCertificates: false,78        clientCertificate: ClientCertificate(79          certificate: securityContext.certificate,80          privateKey: securityContext.privateKey,81        ),82      ),83    ),84    interceptors: interceptor != null ? [interceptor] : [],85  );86}

app/lib/util/rhttp.dart · lines 70–86

Figure II · createRhttpClient() disables rhttp's default certificate verification and instead attaches the device's own self-signed client certificate — LocalSend does its own pinning check rather than trusting a CA, which is why sending works between devices with no shared certificate authority.

Figure III · state machineSendSessionState.status during a transfer

Click a state above.

checkpoint

Check your understanding

Answered in place — nothing is graded, everything is explained. 0 / 3 passed

In SendNotifier.startSession(), what happens when client.prepareUpload() throws a status-401 error?

Which call is actually responsible for streaming a file's bytes to the receiver over HTTPS?

Why does createRhttpClient() set verifyCertificates: false while still attaching a client certificate?