freeport 2.0.0
freeport: ^2.0.0 copied to clipboard
A small, dependency-free Dart library for finding available TCP ports, with ordered preferred ports and hostname support.
Freeport #
A small Dart library for finding available TCP ports. Two functions, no runtime
dependencies. Requires Dart 3.5 or later and a platform that supports dart:io.
Installation #
dart pub add freeport
Or add the dependency to pubspec.yaml:
dependencies:
freeport: ^2.0.0
Usage #
import 'package:freeport/freeport.dart';
Future<void> main() async {
final port = await freePort();
print('Available port: $port');
final preferred = await freePort(
preferred: [8080, 8081],
hostname: 'localhost',
);
print('Preferred or system-assigned port: $preferred');
if (await isAvailablePort(8080, hostname: '127.0.0.1')) {
print('Port 8080 is available on IPv4 loopback');
}
}
API #
Migrating from 1.x #
Invalid port values and unsupported hostname argument types now throw
ArgumentError. Catch or validate these inputs if your code previously relied
on a false result. Unexpected errors also propagate.
Hostnames are resolved instead of silently falling back to IPv4 loopback. Pass
hostname: '127.0.0.1' explicitly if that is the address you need.
isAvailablePort(0) now checks a real binding and can return false.
Functions #
Future<int> freePort({Iterable<int>? preferred, Object? hostname})
Future<bool> isAvailablePort(int port, {Object? hostname})
freePort tries candidates in iteration order and returns the first available
port. Each probe is closed before the next begins. It skips zero entries in
preferred; if the iterable is absent, empty, or has no available candidate,
the operating system assigns a port by binding to 0.
isAvailablePort binds and closes a TCP socket to check availability. Passing
0 checks whether the system can assign a port on the requested address. It
does not identify a particular port.
Ports must be between 0 and 65535. An out-of-range port encountered during
probing throws ArgumentError. isAvailablePort returns false for a bind or
name-resolution SocketException; other errors propagate. freePort skips
candidates whose bind fails and throws if its final system-assigned bind fails.
Addresses #
Both functions accept a String hostname or IP address, or an InternetAddress:
await freePort(hostname: '127.0.0.1');
await freePort(hostname: '::1');
await freePort(hostname: 'localhost');
String names are resolved by Dart's
ServerSocket.bind, which
uses the first resolved address. The address must belong to the local machine;
this library does not scan ports on remote hosts. An invalid hostname is not
silently replaced with loopback. Unsupported argument types throw ArgumentError.
Literal IP strings are parsed directly. When a failed native bind reports the
resolved address, freePort reuses it for the remaining candidates and fallback.
This avoids repeating address lookups for occupied ports. Addresses are not
cached across calls.
The address is selected in this order:
- The explicit
hostnameargument. - The process environment variable
HOST. - The compile-time
HOSTvalue supplied with-DHOST=.... - IPv4 loopback,
127.0.0.1.
HOST=127.0.0.1 dart run example/main.dart
Availability is not a reservation #
Both functions close their probe before returning. Another process can take the port between the check and your own bind. Use the same address for probing and binding, and handle bind failures.
If you control the server, let the operating system assign its port directly and keep the socket open:
import 'dart:io';
Future<void> main() async {
final server = await ServerSocket.bind(InternetAddress.loopbackIPv4, 0);
try {
print('Listening on ${server.port}');
// Handle connections here while the socket stays open.
} finally {
await server.close();
}
}
Development #
dart pub get
dart format --output=none --set-exit-if-changed .
dart analyze --fatal-infos --fatal-warnings .
dart test
CI tests stable Dart on Linux, macOS, and Windows, plus Dart 3.5 on Linux. Formatting and static analysis run once on stable Linux.
Run dart run benchmark/freeport.dart to measure port discovery with IP strings
and localhost, including early success and occupied candidate lists. It uses
local sockets and reports median and 95th-percentile timings after warmup.