README
¶
Net Package
The net package provides network operations for Reglet WASM plugins, implementing a Hexagonal Architecture that separates domain logic from infrastructure adapters.
Overview
This package offers high-level "Check" functions for verifying network connectivity (TCP, DNS, HTTP, SMTP). These functions are designed to be:
- Secure by Default: Using safe defaults for timeouts and configurations.
- Testable: Supporting dependency injection via functional options for mock-based testing.
- WASM-Optimized: Routing traffic through the host environment when running in WASM.
Check Functions
RunTCPCheck
Performs a TCP connection check.
cfg := config.Config{
"host": "example.com",
"port": 443,
"timeout_ms": 5000,
}
result, err := sdknet.RunTCPCheck(ctx, cfg)
RunDNSCheck
Performs a DNS lookup.
cfg := config.Config{
"hostname": "example.com",
"record_type": "A", // A, AAAA, CNAME, MX, TXT, NS
}
result, err := sdknet.RunDNSCheck(ctx, cfg)
RunHTTPCheck
Performs an HTTP request.
cfg := config.Config{
"url": "https://example.com",
"method": "GET",
"expected_status": 200,
}
result, err := sdknet.RunHTTPCheck(ctx, cfg)
RunSMTPCheck
Performs an SMTP connection check.
cfg := config.Config{
"host": "smtp.example.com",
"port": 587,
"use_starttls": true,
}
result, err := sdknet.RunSMTPCheck(ctx, cfg)
Advanced Usage & Testing
The package exposes functional options to inject custom adapters (ports), enabling mock-based unit testing without a WASM runtime.
Mocking TCP
mockDialer := &MyMockTCPDialer{} // Implements ports.TCPDialer
result, err := sdknet.RunTCPCheck(ctx, cfg, sdknet.WithTCPDialer(mockDialer))
Mocking HTTP
mockClient := &MyMockHTTPClient{} // Implements ports.HTTPClient
result, err := sdknet.RunHTTPCheck(ctx, cfg, sdknet.WithHTTPClient(mockClient))
Custom Resolver/Transport
For use cases outside of the check functions, you can create configured clients that use the underlying WASM adapters:
// Create a DNS resolver with custom timeout
resolver := sdknet.NewResolver(
sdknet.WithDNSTimeout(10 * time.Second),
sdknet.WithNameserver("1.1.1.1:53"),
)
// Create an HTTP client
client := sdknet.NewTransport(
sdknet.WithHTTPTimeout(60 * time.Second),
)
Architecture
- Domain/Ports: Interfaces defined in
go/domain/ports(e.g.,TCPDialer,HTTPClient). - Infrastructure/WASM: Adapters in
go/infrastructure/wasmimplement these ports using//go:wasmimport. - Public API:
go/netfunctions orchestrate logic using ports, defaulting to WASM adapters.
This design allows the same code to be tested natively (using mocks) and run in WASM (using host functions).
Documentation
¶
Overview ¶
Package net provides high-level network check functions for SDK plugins.
Index ¶
- func NewResolver(opts ...ResolverOption) ports.DNSResolver
- func NewTransport(opts ...TransportOption) ports.HTTPClient
- func RunDNSCheck(ctx context.Context, cfg config.Config, opts ...DNSCheckOption) (entities.Result, error)
- func RunHTTPCheck(ctx context.Context, cfg config.Config, opts ...HTTPCheckOption) (entities.Result, error)
- func RunSMTPCheck(ctx context.Context, cfg config.Config, opts ...SMTPCheckOption) (entities.Result, error)
- func RunTCPCheck(ctx context.Context, cfg config.Config, opts ...TCPCheckOption) (entities.Result, error)
- type DNSCheckOption
- type HTTPCheckOption
- type ResolverOption
- type SMTPCheckOption
- type TCPCheckOption
- type TransportOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewResolver ¶
func NewResolver(opts ...ResolverOption) ports.DNSResolver
NewResolver creates a new DNS resolver with the given options. Without any options, secure defaults are applied:
- timeout: 5 seconds
- retries: 3
- nameserver: host's default resolver
Example:
// Use defaults
resolver := NewResolver()
// With custom nameserver and timeout
resolver := NewResolver(
WithNameserver("1.1.1.1:53"),
WithDNSTimeout(10*time.Second),
)
func NewTransport ¶
func NewTransport(opts ...TransportOption) ports.HTTPClient
NewTransport creates a new HTTP client with the given options. Without any options, secure defaults are applied:
- timeout: 30 seconds
- maxRedirects: 10
- tlsConfig: system defaults
Example:
// Use defaults
client := NewTransport()
// With custom timeout
client := NewTransport(
WithHTTPTimeout(60*time.Second),
WithMaxRedirects(5),
)
func RunDNSCheck ¶
func RunDNSCheck(ctx context.Context, cfg config.Config, opts ...DNSCheckOption) (entities.Result, error)
RunDNSCheck performs a DNS lookup check. It parses configuration, executes the DNS lookup, and returns a structured Result.
Expected config fields:
- hostname (string, required): Domain name to resolve
- record_type (string, optional): DNS record type (A, AAAA, CNAME, MX, TXT, NS). Default: A
- nameserver (string, optional): Custom nameserver (e.g., "8.8.8.8")
- timeout_ms (int, optional): Lookup timeout in milliseconds (default: 5000)
Returns a Result with:
- Status: "success" if lookup succeeded, "error" if failed
- Data: map containing "records" ([]string) or "mx_records" (for MX queries)
- Error: structured error details if lookup failed
func RunHTTPCheck ¶
func RunHTTPCheck(ctx context.Context, cfg config.Config, opts ...HTTPCheckOption) (entities.Result, error)
RunHTTPCheck performs an HTTP request check. It parses configuration, executes the HTTP request, and returns a structured Result.
Expected config fields:
- url (string, required): Target URL
- method (string, optional): HTTP method (default: GET)
- headers (map[string]string, optional): Request headers
- body (string, optional): Request body
- timeout_ms (int, optional): Request timeout in milliseconds (default: 30000)
- expected_status (int, optional): Expected HTTP status code for validation
- follow_redirects (bool, optional): Whether to follow redirects (default: true)
- max_redirects (int, optional): Maximum redirects to follow (default: 10)
Returns a Result with:
- Status: "success" if request succeeded and matches expectations, "failure" if status mismatch, "error" if request failed
- Data: map containing "status_code", "headers", "body", "latency_ms", "body_truncated"
- Error: structured error details if request failed
func RunSMTPCheck ¶
func RunSMTPCheck(ctx context.Context, cfg config.Config, opts ...SMTPCheckOption) (entities.Result, error)
RunSMTPCheck performs an SMTP connectivity check. It parses configuration, executes the SMTP connection test, and returns a structured Result.
Expected config fields:
- host (string, required): SMTP server hostname
- port (int, required): SMTP server port (typically 25, 465, or 587)
- use_tls (bool, optional): Use implicit TLS (port 465). Default: false
- use_starttls (bool, optional): Upgrade to TLS via STARTTLS (port 587). Default: false
- timeout_ms (int, optional): Connection timeout in milliseconds (default: 30000)
Returns a Result with:
- Status: "success" if connected, "error" if failed
- Data: map containing "connected", "banner", "tls_version", "latency_ms"
- Error: structured error details if connection failed
func RunTCPCheck ¶
func RunTCPCheck(ctx context.Context, cfg config.Config, opts ...TCPCheckOption) (entities.Result, error)
RunTCPCheck performs a TCP connectivity check. It parses configuration, executes the connection test, and returns a structured Result.
Expected config fields:
- host (string, required): Target hostname or IP address
- port (int, required): Target port number (1-65535)
- timeout_ms (int, optional): Connection timeout in milliseconds (default: 5000)
Returns a Result with:
- Status: "success" if connected, "error" if failed
- Data: map containing "connected", "remote_addr", "latency_ms"
- Error: structured error details if connection failed
Types ¶
type DNSCheckOption ¶
type DNSCheckOption func(*dnsCheckConfig)
DNSCheckOption is a functional option for configuring DNS checks.
func WithDNSResolver ¶
func WithDNSResolver(r ports.DNSResolver) DNSCheckOption
WithDNSResolver sets the DNS resolver to use for the check. This is useful for injecting mocks during testing.
type HTTPCheckOption ¶
type HTTPCheckOption func(*httpCheckConfig)
HTTPCheckOption is a functional option for configuring HTTP checks.
func WithHTTPClient ¶
func WithHTTPClient(c ports.HTTPClient) HTTPCheckOption
WithHTTPClient sets the HTTP client to use for the check. This is useful for injecting mocks during testing.
type ResolverOption ¶
type ResolverOption func(*resolverConfig)
ResolverOption is a functional option for configuring a WasmResolver. Use With* functions to create options.
func WithDNSTimeout ¶
func WithDNSTimeout(d time.Duration) ResolverOption
WithDNSTimeout sets the timeout for DNS queries. Default is 5 seconds per constitution specification. A zero or negative duration is ignored (uses default).
func WithNameserver ¶
func WithNameserver(ns string) ResolverOption
WithNameserver sets a custom DNS nameserver address. The address should be in "host:port" format (e.g., "8.8.8.8:53"). If port is omitted, ":53" is assumed. If not specified, the host's default resolver is used.
func WithRetries ¶
func WithRetries(n int) ResolverOption
WithRetries sets the number of retry attempts for failed DNS queries. Default is 3 retries. A negative value is ignored (uses default). Setting to 0 disables retries (single attempt only).
type SMTPCheckOption ¶
type SMTPCheckOption func(*smtpCheckConfig)
SMTPCheckOption is a functional option for configuring SMTP checks.
func WithSMTPClient ¶
func WithSMTPClient(c ports.SMTPClient) SMTPCheckOption
WithSMTPClient sets the SMTP client to use for the check. This is useful for injecting mocks during testing.
type TCPCheckOption ¶
type TCPCheckOption func(*tcpCheckConfig)
TCPCheckOption is a functional option for configuring TCP checks.
func WithTCPDialer ¶
func WithTCPDialer(d ports.TCPDialer) TCPCheckOption
WithTCPDialer sets the TCP dialer to use for the check. This is useful for injecting mocks during testing.
type TransportOption ¶
type TransportOption func(*transportConfig)
TransportOption is a functional option for configuring a WasmTransport. Use With* functions to create options.
func WithHTTPTimeout ¶
func WithHTTPTimeout(d time.Duration) TransportOption
WithHTTPTimeout sets the timeout for HTTP requests. Default is 30 seconds per constitution specification. A zero or negative duration is ignored (uses default).
func WithMaxRedirects ¶
func WithMaxRedirects(n int) TransportOption
WithMaxRedirects sets the maximum number of redirects to follow. Default is 10 redirects. A negative value is ignored (uses default). Setting to 0 disables following redirects.
func WithTLSConfig ¶
func WithTLSConfig(cfg *tls.Config) TransportOption
WithTLSConfig sets a custom TLS configuration. If nil is passed, the system default TLS configuration is used.
Source Files