Skip to main content

rpc_dart_socket 0.2.0 copy "rpc_dart_socket: ^0.2.0" to clipboard
rpc_dart_socket: ^0.2.0 copied to clipboard

Unix domain socket and TCP transport for rpc_dart on the Dart VM. A caller connect and a server that owns its listening socket.

rpc_dart_socket #

Unix domain socket and TCP transport for rpc_dart on the Dart VM. It supports all four call kinds (unary, server stream, client stream, bidirectional) over one connection.

Use it for local IPC between processes on one machine (a Unix socket), or for a plain TCP link on a network you trust. This is the rpc_dart frame protocol over a byte stream, not gRPC. Both peers must be rpc_dart with this package.

Contracts, endpoints, errors and RpcSecurityPolicy are documented in rpc_dart. This README covers only what is specific to sockets.

Install #

dependencies:
  rpc_dart_socket: ^0.1.0

VM only: it is built on dart:io sockets.

Addresses #

import 'dart:io';

import 'package:rpc_dart_socket/rpc_dart_socket.dart';

const unix = RpcSocketAddress.unix('/tmp/app/rpc.sock');
final tcp = RpcSocketAddress.tcp(InternetAddress.loopbackIPv4, 7000);

A Unix socket path is capped by the OS: 104 bytes on macOS, 108 on Linux. Put it in a directory only its owner can enter, because whoever can connect to the socket file can make calls.

Server #

import 'package:rpc_dart/rpc_dart.dart';
import 'package:rpc_dart_socket/rpc_dart_socket.dart';

Future<RpcSocketServer> serve(RpcResponderContract contract) async {
  final server = RpcSocketServer.createWithContracts(
    address: const RpcSocketAddress.unix('/tmp/app/rpc.sock'),
    contracts: [contract],
  );
  await server.start();
  return server;
}

The server owns its listening socket: start() binds it, stop() closes it, and a later start() binds again. stop(drainTimeout: ...) stops accepting, lets running calls finish within the budget, then closes.

Parameter Default Meaning
policy RpcSecurityPolicy() Limits applied to every connection.
maxConnections none Cap on concurrent connections, those still in their handshake included. A connection past it is closed at once.
prefaceTimeout 10 s How long an accepted socket may take to send its preface. No endpoint exists before it arrives.
mode required What each connection gets: RpcResponderMode(register) or RpcPeerMode(register) for peer mode, where both sides may start calls. The register adds the contracts.
onConnectionOpened / onConnectionClosed none Observability. Every opened connection is reported closed once.

A stale socket file is replaced. A running server holds an exclusive lock on <path>.lock beside its socket. start() takes that lock first and throws a SocketException if a running server holds it, or if the lock file cannot be created. With the lock taken, a socket file left by a server that crashed is deleted when a connect to it is refused, and the bind is retried. A path that is not a socket is left alone and start() throws. The lock belongs to the process, so use one path per process. A clean stop() removes the socket file and the lock file.

Client #

import 'package:rpc_dart/rpc_dart.dart';
import 'package:rpc_dart_socket/rpc_dart_socket.dart';

Future<void> client() async {
  final transport = await connectRpcSocket(
    const RpcSocketAddress.unix('/tmp/app/rpc.sock'),
  );
  final endpoint = RpcCallerEndpoint(transport: transport);

  // ... make calls through a generated caller or the endpoint ...

  await endpoint.close(); // closes the transport and the socket
}

connectRpcSocket returns once the socket is connected. Calls can start at once. transport.ready completes when the server's preface has arrived, which is what tells an rpc_dart server apart from any other process listening there.

connectTimeout (30 s by default) bounds the whole open: the connect and the server's preface. A failed connect throws an RpcStatusException with UNAVAILABLE. cancellationToken abandons the connect: the pending socket is closed at once and the call throws an RpcCancelledException.

Reconnect #

The transport does not reconnect itself: a dropped socket closes it. For a client that comes back, give RpcClientConnection from rpc_dart a factory that calls connectRpcSocket with the token it is handed. It builds a fresh transport per connection, carries the stream id cursor across, and waits for ready before it reports Online. The token lets dispose() end a connect still in progress, which against a host that never answers would otherwise run until connectTimeout.

import 'package:rpc_dart/rpc_dart.dart';
import 'package:rpc_dart_socket/rpc_dart_socket.dart';

RpcCallerEndpoint reconnectingCaller() {
  final connection = RpcClientConnection(
    transportFactory: (cancellation) => connectRpcSocket(
      const RpcSocketAddress.unix('/tmp/app/rpc.sock'),
      cancellationToken: cancellation,
    ),
  );
  connection.connect();
  return RpcCallerEndpoint(transport: connection.transport);
}

Calls in flight when the socket drops are lost; reissue them once the connection is Online again.

The preface #

The client writes eight bytes first, rpcdart and the frame protocol version, and the server answers with the same eight before anything else. This is the preface every rpc_dart channel transport opens with, see RpcChannelFrame.preface. A bare socket otherwise says nothing about who answered it. A peer that never speaks, or that speaks another protocol on the same address, would look exactly like an idle server.

Peer ready and every call fail with
Closes or never sends a preface within the timeout UNAVAILABLE
Sends rpcdart with another version FAILED_PRECONDITION
Sends anything else UNKNOWN

The server's timeout is prefaceTimeout (10 s by default); the client's is what is left of connectTimeout.

Limits of a raw socket #

  • No close reason. A raw socket has no close code. A connection closed for a protocol violation reaches the peer as an ordinary end of stream, which its caller reports as UNAVAILABLE.
  • No keepalive. A Unix socket cannot go half-open: the peer's death is an end of stream. A TCP path through a NAT or a load balancer can, and then a call on it hangs until its deadline. Give calls deadlines.
  • No TLS. Use TCP only on a network you trust, or put the link inside one.
  • TCP_NODELAY is on for TCP sockets: rpc_dart writes the frames of one event-loop turn together and then at once, and Nagle's algorithm would hold a small request back for a round trip.
0
likes
160
points
731
downloads

Documentation

API reference

Publisher

verified publisherrpc.nogipx.dev

Weekly Downloads

Unix domain socket and TCP transport for rpc_dart on the Dart VM. A caller connect and a server that owns its listening socket.

Homepage
Repository (GitHub)
View/report issues

Topics

#rpc #socket #ipc

License

MIT (license)

Dependencies

rpc_dart

More

Packages that depend on rpc_dart_socket