Atlas

Appearance

@univ-lehavre/atlas-net ​

Network diagnostic utilities for Atlas, built with Effect.

About ​

This package provides typed and functional network diagnostic tools for Atlas applications. It is used by CLI tools to verify connectivity to REDCap servers and other services.

Features ​

  • DNS Resolution: Verify hostname resolution
  • TCP Ping: Test if a port is open and accessible
  • TLS Handshake: Verify SSL/TLS certificates
  • Internet Check: Quick connectivity test
  • Branded Types: Typed network values with runtime validation
  • Constants: Default timeouts and network configuration

Installation ​

bash
pnpm add @univ-lehavre/atlas-net effect

Usage ​

typescript
import { Effect } from 'effect';
import {
  dnsResolve,
  tcpPing,
  tlsHandshake,
  checkInternet,
  Hostname,
  Port,
} from '@univ-lehavre/atlas-net';

// Check Internet connectivity
const internet = await Effect.runPromise(checkInternet());
console.log(`Internet: ${internet.status}`);

// Resolve a hostname
const hostname = Hostname('example.com');
const dns = await Effect.runPromise(dnsResolve(hostname));
console.log(`DNS: ${dns.status} -> ${dns.message}`);

// Test TCP connection
const port = Port(443);
const tcp = await Effect.runPromise(tcpPing(hostname, port));
console.log(`TCP: ${tcp.status} (${tcp.latencyMs}ms)`);

// Verify TLS certificate
const tls = await Effect.runPromise(tlsHandshake(hostname, port));
console.log(`TLS: ${tls.status} - ${tls.message}`);

Complete Diagnostic Pipeline ​

typescript
import { Effect } from 'effect';
import {
  dnsResolve,
  tcpPing,
  tlsHandshake,
  checkInternet,
  Hostname,
  Port,
} from '@univ-lehavre/atlas-net';

const diagnose = (host: Hostname, port: Port) =>
  Effect.all([checkInternet(), dnsResolve(host), tcpPing(host, port), tlsHandshake(host, port)]);

const steps = await Effect.runPromise(diagnose(Hostname('example.com'), Port(443)));
steps.forEach((step) => {
  console.log(`${step.name}: ${step.status} (${step.latencyMs}ms)`);
});

Branded Types ​

The package provides branded types with runtime validation via Effect's Brand module.

typescript
import { Hostname, IpAddress, Port, TimeoutMs, SafeApiUrl } from '@univ-lehavre/atlas-net';

// Create validated values
const hostname = Hostname('example.com'); // Validated hostname (RFC 1123)
const ip = IpAddress('192.168.1.1'); // Validated IPv4 address
const port = Port(8080); // Validated port (1-65535)
const timeout = TimeoutMs(5000); // Validated timeout (0-600000ms)
const url = SafeApiUrl('https://api.example.com/v1/'); // Secure URL

API ​

Functions ​

FunctionDescription
dnsResolve(hostname)Resolves a hostname to an IP address
tcpPing(host, port, options?)Tests TCP connectivity
tlsHandshake(host, port, options?)Verifies TLS certificate
checkInternet(options?)Checks Internet connectivity

Types ​

TypeDescription
HostnameRFC 1123 validated hostname or IP address
IpAddressValidated IPv4 or IPv6 address
PortPort number (1-65535)
TimeoutMsTimeout in milliseconds (0-600000)
SafeApiUrlSecure URL for API communication
DiagnosticStepResult of a diagnostic step

Constants ​

typescript
import {
  DEFAULT_TCP_TIMEOUT_MS, // 3000ms
  DEFAULT_TLS_TIMEOUT_MS, // 5000ms
  INTERNET_CHECK_HOST, // '1.1.1.1' (Cloudflare DNS)
  HTTPS_PORT, // 443
} from '@univ-lehavre/atlas-net';

Documentation ​

Organization ​

This package is part of Atlas, a set of tools developed by Le Havre Normandie University to facilitate research and collaboration between researchers.

Atlas is developed as part of two projects led by Le Havre Normandie University:

Le Havre Normandie University     Campus Polytechnique des Territoires Maritimes et Portuaires     EUNICoast

License ​

MIT

See ​

README.md for full documentation

Interfaces ​

InterfaceDescription
DiagnosticResultAggregated result of multiple diagnostic steps.
DiagnosticStepResult of a single diagnostic step.
TcpPingOptionsOptions for TCP ping operation.
TlsHandshakeOptionsOptions for TLS handshake operation.

Type Aliases ​

Type AliasDescription
DiagnosticStatusStatus of a diagnostic step.
HostUnion type for host parameter. Accepts either a Hostname or IpAddress branded type. Used in function signatures that accept both hostnames and IP addresses.
HostnameBranded type for hostnames. Validates according to RFC 1123. Also accepts valid IP addresses.
IpAddressBranded type for IP addresses. Accepts valid IPv4 (e.g., '192.168.1.1') or IPv6 (e.g., '::1') addresses.
PortBranded type for port numbers. Valid range: 1 to 65535.
SafeApiUrlBranded type for safe API URLs.
TimeoutMsBranded type for timeout values in milliseconds. Valid range: 0 to 600000 (10 minutes).

Variables ​

VariableDescription
DEFAULT_INTERNET_CHECK_TIMEOUT_MSDefault timeout for internet connectivity checks in milliseconds.
DEFAULT_TCP_TIMEOUT_MSDefault timeout for TCP connections in milliseconds.
DEFAULT_TLS_TIMEOUT_MSDefault timeout for TLS handshakes in milliseconds.
HostnameConstructor for Hostname branded type with validation.
HTTPS_PORTStandard HTTPS port.
INTERNET_CHECK_HOSTHost used for internet connectivity checks (Cloudflare DNS).
IpAddressConstructor for IpAddress branded type with validation.
PortConstructor for Port branded type with validation.
SafeApiUrlConstructor for SafeApiUrl branded type with validation.
TimeoutMsConstructor for TimeoutMs branded type with validation.

Functions ​

FunctionDescription
checkInternetChecks basic internet connectivity by pinging Cloudflare's DNS server.
dnsResolveResolves a hostname to an IP address using DNS lookup.
tcpPingTests TCP connectivity to a host and port.
tlsHandshakeTests TLS/SSL connectivity and validates the server certificate.

References ​

HostnameType ​

Renames and re-exports Hostname

IpAddressType ​

Renames and re-exports IpAddress

PortType ​

Renames and re-exports Port

SafeApiUrlType ​

Renames and re-exports SafeApiUrl

TimeoutMsType ​

Renames and re-exports TimeoutMs