README

This project contains tools to resolve SRV records for AWS Cloud Map.

Installation

Install the package with Composer:

composer require bookunited/srv-tools

Requirements

The package requires:

PHP ^8.5
Guzzle ^7.15.5 or ^8.1
PSR-3 logging ^3.0
PSR-16 caching ^3.0

PSR-3 logging and PSR-16 caching are optional features. The corresponding dependencies are only used when a logger or cache is passed to the middleware or resolver.

SRVResolver

Resolve SRV records without using Guzzle:

use Bookunited\SRVTools\SRV\SRVResolver;

$resolver = new SRVResolver();
$records = $resolver->resolve('_http._tcp.my-api.local');

foreach ($records as $record) {
    echo $record->target() . ':' . $record->port();
}

SRVResolver accepts an optional PSR-16 cache via cache:. Successful non-empty results use shortest-record TTL; cache failures fall back to DNS.

When no SRV records are found, resolve() returns an empty array. DNS support unavailability or DNS lookup failures throw RuntimeException.

Guzzle\SRVMiddleware

Use middleware to resolve srv-http requests and retry connection failures on other SRV targets:

use Bookunited\SRVTools\Guzzle\SRVMiddleware;
use Bookunited\SRVTools\SRV\SRVResolver;
use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;

$resolver = new SRVResolver();

$stack = HandlerStack::create();
$stack->push(new SRVMiddleware($resolver));

$client = new Client([
    'handler' => $stack,
]);

$responseHttp = $client->get(
    'srv-http://_http._tcp.my-api.local/v1/users',
);

Pass an optional PSR-3 logger as logger: to record failed SRV targets during failover. No logger means no retry logging.

Pass serviceHost: to override the HTTP Host header while still connecting to resolved SRV targets:

$stack->push(new SRVMiddleware(
    resolver: $resolver,
    serviceHost: 'orders.internal',
));

Retries occur only for connection failures. Applications should use care with non-idempotent requests because a connection failure cannot always prove that the remote service did not process the request.

SRVMiddleware throws NoSRVRecordsException when an srv-http request has no SRV records. Unsupported srv-* schemes and an empty serviceHost throw InvalidArgumentException. Non-connection failures from Guzzle are propagated unchanged. If every SRV target fails to connect, the middleware performs one fresh SRV lookup before throwing the final ConnectException. This refresh is attempted at most once per request.

Development

Run checks with the Composer scripts:

composer format
composer format-check
composer lint
composer analyze
composer test
composer verify

bookunited / srv-tools

Package info

Security

Statistics