Documentation
¶
Overview ¶
Package ipify provides a small client to resolve the current instance public IP address using the ipify service (https://www.ipify.org/).
Problem ¶
Services running behind NAT, cloud load balancers, or dynamic outbound egress often need to discover their externally visible IP address at runtime (for allow-list updates, diagnostics, or registration workflows). Implementing this from scratch requires HTTP setup, timeout handling, status validation, and error fallback logic.
Solution ¶
This package wraps those concerns in a focused Client API:
- New creates a configurable ipify client.
- Client.GetPublicIP performs the request and returns the resolved IP.
- Client.HealthCheck probes endpoint reachability for parity with the other nurago HTTP clients.
The default configuration uses:
- endpoint: https://api.ipify.org
- timeout: 4 seconds
Use WithURL, WithTimeout, WithHTTPClient, and WithErrorIP to adapt the client to custom endpoints, transport stacks, and fallback policies. A non-positive timeout is clamped to the default; an API URL that is missing, unparseable, or not http/https with a host is rejected by New.
Error Fallback Behavior ¶
When request creation, transport, status-code validation, or body reading fails, Client.GetPublicIP returns the configured error-IP value together with the error. By default the fallback string is empty, but it can be set (for example to "0.0.0.0") via WithErrorIP. The response body is whitespace-trimmed and an empty body is treated as a failure.
Errors ¶
Configuration problems are reported at construction time with errors matching the exported sentinel ErrInvalidOptions. A nil or empty response body from the endpoint surfaces as ErrInvalidResponse. Match the sentinels with errors.Is.
IPv6 Note ¶
The default endpoint resolves standard ipify behavior. To force IPv6-capable resolution, point the client to `https://api64.ipify.org` via WithURL.
Benefits ¶
ipify gives applications a minimal, testable, and timeout-safe way to discover public IP information without duplicating HTTP boilerplate.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidOptions is returned by New when the configured API URL is // missing, unparseable, or does not use an http/https scheme with a host. ErrInvalidOptions = errors.New("ipify: missing or invalid client options") // ErrInvalidResponse is returned by GetPublicIP when the endpoint returns a // nil response body or an empty (whitespace-only) payload. ErrInvalidResponse = errors.New("ipify: invalid response") )
Sentinel errors returned by the package. Match them with errors.Is so callers can distinguish configuration problems from response failures.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client resolves public IP addresses through an ipify-compatible endpoint.
func New ¶
New constructs an ipify client with validated configuration.
It applies options, initializes a default HTTP client when needed, and validates the configured API URL. A non-positive timeout is silently clamped to the default rather than rejected, so a misconfigured timeout cannot make every request fail with an already-expired context. An API URL that is missing, unparseable, or that does not use an http/https scheme with a host is rejected with an error matching ErrInvalidOptions.
func (*Client) GetPublicIP ¶
GetPublicIP resolves the instance public IP through the configured ipify endpoint.
On any request or response failure, it returns the configured fallback errorIP together with the error.
func (*Client) HealthCheck ¶
HealthCheck verifies that the configured ipify endpoint is reachable and returns a usable public IP.
It performs a GetPublicIP call, discards the resolved address, and returns only the error. It exists for parity with the other nurago HTTP clients that expose a HealthCheck probe.
type HTTPClient ¶
HTTPClient is the minimal HTTP transport contract used by Client.
type Option ¶
type Option func(c *Client)
Option is the interface that allows to set client options.
func WithErrorIP ¶
WithErrorIP sets the fallback IP string returned on failures.
func WithHTTPClient ¶
func WithHTTPClient(hc HTTPClient) Option
WithHTTPClient injects a custom HTTP client implementation.
This is useful for testing, tracing, proxies, or custom transports.
func WithTimeout ¶
WithTimeout sets the request timeout used by GetPublicIP.
func WithURL ¶
WithURL sets the ipify service endpoint URL.
For IPv6-aware responses, use https://api64.ipify.org.
Source Files