cloudip

package module
v0.0.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 13, 2026 License: MIT Imports: 10 Imported by: 0

README

go-cloudip

Go Reference Go Report Card

Fast cloud provider IP detection for Go. Determine if an IP address belongs to AWS, GCP, Azure, Cloudflare, DigitalOcean, or Oracle Cloud with sub-microsecond lookup times.

Features

  • Fast lookups - Sub-microsecond performance using Patricia trie
  • Multiple providers - AWS, GCP, Azure, Cloudflare, DigitalOcean, Oracle
  • Automatic updates - Optional background refresh from cloudip-db
  • Offline support - Works without network using embedded data
  • Thread-safe - Concurrent lookups with lock-free reads
  • Zero config - First run fetches latest data and caches it; works offline afterwards
  • Embedded fallback - Includes compiled-in data for air-gapped environments

Installation

go get github.com/rezmoss/go-cloudip

Quick Start

package main

import (
    "fmt"
    "github.com/rezmoss/go-cloudip"
)

func main() {
    // Simple provider detection
    if cloudip.IsAWS("52.94.76.1") {
        fmt.Println("This is an AWS IP")
    }

    // Get provider name
    provider := cloudip.GetProvider("34.64.0.1")
    fmt.Println("Provider:", provider) // "gcp"

    // Check if any cloud provider
    if cloudip.IsCloudProvider("104.16.0.1") {
        fmt.Println("This is a cloud IP")
    }

    // Detailed lookup with region and service info
    result := cloudip.Lookup("52.94.76.1")
    if result.Found {
        fmt.Printf("Provider: %s, Region: %s, Service: %s\n",
            result.Provider, result.Region, result.Service)
    }
}

How Data Loading Works

On initialization, the detector loads IP range data with this priority:

  1. Network - Fetches latest data from cloudip-db and caches locally
  2. Cache - Uses previously cached data if network unavailable
  3. Embedded - Falls back to compiled-in data (for air-gapped environments)

This means:

  • First run: Automatically downloads latest IP ranges and caches them (~/.cache/go-cloudip)
  • Subsequent runs: Still tries network first, but has cache as reliable fallback
  • Offline/air-gapped: Use WithOffline() to skip network entirely

API Reference

Package-Level Functions

These use a default global detector that initializes automatically:

// Provider detection
cloudip.IsAWS(ip string) bool
cloudip.IsGCP(ip string) bool
cloudip.IsAzure(ip string) bool
cloudip.IsCloudflare(ip string) bool
cloudip.IsDigitalOcean(ip string) bool
cloudip.IsOracle(ip string) bool
cloudip.IsCloudProvider(ip string) bool

// Get provider
cloudip.GetProvider(ip string) Provider

// Detailed lookup
cloudip.Lookup(ip string) LookupResult

// Metadata
cloudip.Version() string
cloudip.RangeCount() int
cloudip.Providers() []string

// Updates
cloudip.Update(ctx context.Context) error
cloudip.CheckUpdate(ctx context.Context) (bool, *VersionInfo, error)
Custom Detector

For more control, create a custom detector:

detector, err := cloudip.NewDetector(
    cloudip.WithDataDir("./cache"),
    cloudip.WithAutoUpdate(24 * time.Hour),
)
if err != nil {
    log.Fatal(err)
}
defer detector.Close()

result := detector.Lookup("52.94.76.1")
Configuration Options
Option Description
WithDataDir(dir) Set cache directory (default: ~/.cache/go-cloudip)
WithAutoUpdate(interval) Enable background updates (minimum: 1 hour)
WithOffline() Disable network, use embedded data only
WithHTTPClient(client) Custom HTTP client for requests
WithDataURL(url) Custom data URL (for mirrors)
WithVersionURL(url) Custom version URL
WithNoCache() Disable file caching
Types
// Provider represents a cloud provider
type Provider string

const (
    ProviderAWS         Provider = "aws"
    ProviderGCP         Provider = "gcp"
    ProviderAzure       Provider = "azure"
    ProviderCloudflare  Provider = "cloudflare"
    ProviderDigitalOcean Provider = "digitalocean"
    ProviderOracle      Provider = "oracle"
    ProviderUnknown     Provider = ""
)

// LookupResult contains detailed information about an IP
type LookupResult struct {
    Found    bool     // Whether IP was found
    Provider Provider // Cloud provider
    Region   string   // Geographic region (e.g., "us-east-1")
    Service  string   // Service name (e.g., "EC2", "S3")
    CIDR     string   // Matched IP range
}

Usage Examples

Offline Mode

For air-gapped environments:

detector, _ := cloudip.NewDetector(cloudip.WithOffline())
defer detector.Close()

// Uses only embedded data, no network requests
result := detector.Lookup("52.94.76.1")
With Auto-Update

Keep data fresh automatically:

detector, _ := cloudip.NewDetector(
    cloudip.WithDataDir("/var/cache/cloudip"),
    cloudip.WithAutoUpdate(24 * time.Hour),
)
defer detector.Close()

// Data refreshes in background every 24 hours
Using netip.Addr (Faster)

For high-performance scenarios:

import "net/netip"

addr, _ := netip.ParseAddr("52.94.76.1")
result := cloudip.LookupAddr(addr)
isAWS := cloudip.IsAWSAddr(addr)
Check for Updates
ctx := context.Background()
hasUpdate, info, err := cloudip.CheckUpdate(ctx)
if hasUpdate {
    fmt.Printf("New version: %s (%d ranges)\n", info.Version, info.Ranges)
    cloudip.Update(ctx) // Apply update
}

Performance

Operation Time
IPv4 Lookup ~200-300 ns
IPv6 Lookup ~200-300 ns
LookupAddr (netip.Addr) ~200-250 ns
Data load + parse ~50 ms

All lookups are sub-microsecond. Memory usage: ~10-15 MB for all providers loaded.

Data Source

IP ranges are sourced from cloud-provider-ip-addresses and compiled daily into MessagePack format by cloudip-db.

License

MIT License - see LICENSE file.

Documentation

Overview

Package cloudip provides fast cloud provider IP detection.

It determines whether an IP address belongs to AWS, GCP, Azure, Cloudflare, DigitalOcean, or Oracle Cloud with sub-microsecond lookup times using a Patricia trie data structure.

Quick Start

Use package-level functions for simple lookups: 

if cloudip.IsAWS("52.94.76.1") {
    fmt.Println("This is an AWS IP")
}

provider := cloudip.GetProvider("34.64.0.1")
fmt.Println("Provider:", provider) // "gcp"

result := cloudip.Lookup("52.94.76.1")
if result.Found {
    fmt.Printf("Provider: %s, Region: %s\n", result.Provider, result.Region)
}

Custom Detector

For more control, create a custom Detector: 

detector, err := cloudip.NewDetector(
    cloudip.WithDataDir("./cache"),
    cloudip.WithAutoUpdate(24 * time.Hour),
)
if err != nil {
    log.Fatal(err)
}
defer detector.Close()

result := detector.Lookup("52.94.76.1")

High Performance

For best performance, use netip.Addr directly: 

addr, _ := netip.ParseAddr("52.94.76.1")
result := cloudip.LookupAddr(addr)

Data Source

IP ranges are sourced from official cloud provider publications and compiled into an embedded database that can be updated at runtime.

Package cloudip provides fast cloud provider IP detection.

It can determine if an IP address belongs to major cloud providers (AWS, GCP, Azure, Cloudflare, DigitalOcean, Oracle) with sub-microsecond lookup times using a Patricia trie data structure.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsAWS 

func IsAWS(ip string) bool

IsAWS returns true if the IP belongs to AWS.

func IsAWSAddr 

func IsAWSAddr(addr netip.Addr) bool

IsAWSAddr returns true if the IP belongs to AWS.

func IsAzure 

func IsAzure(ip string) bool

IsAzure returns true if the IP belongs to Microsoft Azure.

func IsAzureAddr 

func IsAzureAddr(addr netip.Addr) bool

IsAzureAddr returns true if the IP belongs to Microsoft Azure.

func IsCloudProvider 

func IsCloudProvider(ip string) bool

IsCloudProvider returns true if the IP belongs to any cloud provider.

func IsCloudProviderAddr 

func IsCloudProviderAddr(addr netip.Addr) bool

IsCloudProviderAddr returns true if the IP belongs to any cloud provider.

func IsCloudflare 

func IsCloudflare(ip string) bool

IsCloudflare returns true if the IP belongs to Cloudflare.

func IsCloudflareAddr 

func IsCloudflareAddr(addr netip.Addr) bool

IsCloudflareAddr returns true if the IP belongs to Cloudflare.

func IsDigitalOcean 

func IsDigitalOcean(ip string) bool

IsDigitalOcean returns true if the IP belongs to DigitalOcean.

func IsDigitalOceanAddr 

func IsDigitalOceanAddr(addr netip.Addr) bool

IsDigitalOceanAddr returns true if the IP belongs to DigitalOcean.

func IsGCP 

func IsGCP(ip string) bool

IsGCP returns true if the IP belongs to Google Cloud.

func IsGCPAddr 

func IsGCPAddr(addr netip.Addr) bool

IsGCPAddr returns true if the IP belongs to Google Cloud.

func IsOracle 

func IsOracle(ip string) bool

IsOracle returns true if the IP belongs to Oracle Cloud.

func IsOracleAddr 

func IsOracleAddr(addr netip.Addr) bool

IsOracleAddr returns true if the IP belongs to Oracle Cloud.

func Providers 

func Providers() []string

Providers returns the list of providers from the default detector.

func RangeCount 

func RangeCount() int

RangeCount returns the number of IP ranges loaded in the default detector.

func Update 

func Update(ctx context.Context) error

Update fetches the latest data using the default detector.

func Version 

func Version() string

Version returns the data version string from the default detector.

Types

type Detector 

type Detector struct {
	// contains filtered or unexported fields
}

Detector is the main type for cloud IP detection. It is safe for concurrent use.

func NewDetector 

func NewDetector(opts ...Option) (*Detector, error)

NewDetector creates a new Detector with the given options. By default, it loads embedded data and can fetch updates from GitHub.

func (*Detector) CheckUpdate 

func (d *Detector) CheckUpdate(ctx context.Context) (bool, *source.VersionInfo, error)

CheckUpdate checks if a new version is available. Returns true if the remote version is newer than the local version.

func (*Detector) Close 

func (d *Detector) Close() error

Close stops background updates and releases resources.

func (*Detector) GetProvider 

func (d *Detector) GetProvider(ip string) Provider

GetProvider returns the provider for the given IP, or empty string if not found.

func (*Detector) GetProviderAddr 

func (d *Detector) GetProviderAddr(addr netip.Addr) Provider

GetProviderAddr returns the provider for the given IP address.

func (*Detector) IsAWS 

func (d *Detector) IsAWS(ip string) bool

IsAWS returns true if the IP belongs to AWS.

func (*Detector) IsAWSAddr 

func (d *Detector) IsAWSAddr(addr netip.Addr) bool

IsAWSAddr returns true if the IP belongs to AWS.

func (*Detector) IsAzure 

func (d *Detector) IsAzure(ip string) bool

IsAzure returns true if the IP belongs to Microsoft Azure.

func (*Detector) IsAzureAddr 

func (d *Detector) IsAzureAddr(addr netip.Addr) bool

IsAzureAddr returns true if the IP belongs to Microsoft Azure.

func (*Detector) IsCloudProvider 

func (d *Detector) IsCloudProvider(ip string) bool

IsCloudProvider returns true if the IP belongs to any cloud provider.

func (*Detector) IsCloudProviderAddr 

func (d *Detector) IsCloudProviderAddr(addr netip.Addr) bool

IsCloudProviderAddr returns true if the IP belongs to any cloud provider.

func (*Detector) IsCloudflare 

func (d *Detector) IsCloudflare(ip string) bool

IsCloudflare returns true if the IP belongs to Cloudflare.

func (*Detector) IsCloudflareAddr 

func (d *Detector) IsCloudflareAddr(addr netip.Addr) bool

IsCloudflareAddr returns true if the IP belongs to Cloudflare.

func (*Detector) IsDigitalOcean 

func (d *Detector) IsDigitalOcean(ip string) bool

IsDigitalOcean returns true if the IP belongs to DigitalOcean.

func (*Detector) IsDigitalOceanAddr 

func (d *Detector) IsDigitalOceanAddr(addr netip.Addr) bool

IsDigitalOceanAddr returns true if the IP belongs to DigitalOcean.

func (*Detector) IsGCP 

func (d *Detector) IsGCP(ip string) bool

IsGCP returns true if the IP belongs to Google Cloud.

func (*Detector) IsGCPAddr 

func (d *Detector) IsGCPAddr(addr netip.Addr) bool

IsGCPAddr returns true if the IP belongs to Google Cloud.

func (*Detector) IsOracle 

func (d *Detector) IsOracle(ip string) bool

IsOracle returns true if the IP belongs to Oracle Cloud.

func (*Detector) IsOracleAddr 

func (d *Detector) IsOracleAddr(addr netip.Addr) bool

IsOracleAddr returns true if the IP belongs to Oracle Cloud.

func (*Detector) Lookup 

func (d *Detector) Lookup(ip string) LookupResult

Lookup returns information about the given IP address.

func (*Detector) LookupAddr 

func (d *Detector) LookupAddr(addr netip.Addr) LookupResult

LookupAddr returns information about the given IP address.

func (*Detector) Providers 

func (d *Detector) Providers() []string

Providers returns the list of providers in the database.

func (*Detector) RangeCount 

func (d *Detector) RangeCount() int

RangeCount returns the number of IP ranges loaded.

func (*Detector) Update 

func (d *Detector) Update(ctx context.Context) error

Update fetches the latest data and updates the detector. This is safe to call concurrently.

func (*Detector) Version 

func (d *Detector) Version() string

Version returns the data version string.

type LookupResult 

type LookupResult struct {
	// Found indicates whether the IP was found in any cloud provider range.
	Found bool

	// Provider is the cloud provider that owns this IP range.
	Provider Provider

	// Region is the geographic region (e.g., "us-east-1", "europe-west1").
	// May be empty if not available.
	Region string

	// Service is the cloud service (e.g., "EC2", "S3", "CLOUDFRONT").
	// May be empty if not available.
	Service string

	// CIDR is the IP range that matched.
	CIDR string
}

LookupResult contains information about an IP address lookup.

func Lookup 

func Lookup(ip string) LookupResult

Lookup returns information about the given IP address using the default detector.

func LookupAddr 

func LookupAddr(addr netip.Addr) LookupResult

LookupAddr returns information about the given IP address using the default detector.

type Option 

type Option func(*options)

Option is a functional option for configuring the Detector.

func WithAutoUpdate 

func WithAutoUpdate(interval time.Duration) Option

WithAutoUpdate enables automatic background updates at the given interval. Minimum interval is 1 hour. Use zero to disable (default).

func WithDataDir 

func WithDataDir(dir string) Option

WithDataDir sets the directory for caching data. Set to empty string to disable caching.

func WithDataURL 

func WithDataURL(url string) Option

WithDataURL overrides the default data URL. Use this if you're hosting your own cloudip-db mirror.

func WithHTTPClient 

func WithHTTPClient(client *http.Client) Option

WithHTTPClient sets a custom HTTP client for network requests.

func WithNoCache 

func WithNoCache() Option

WithNoCache disables the file cache.

func WithOffline 

func WithOffline() Option

WithOffline disables all network access. The detector will only use embedded data.

func WithVersionURL 

func WithVersionURL(url string) Option

WithVersionURL overrides the default version URL.

type Provider 

type Provider string

Provider represents a cloud provider. 

const (
	ProviderUnknown      Provider = ""
	ProviderAWS          Provider = "aws"
	ProviderGCP          Provider = "gcp"
	ProviderAzure        Provider = "azure"
	ProviderCloudflare   Provider = "cloudflare"
	ProviderDigitalOcean Provider = "digitalocean"
	ProviderOracle       Provider = "oracle"
)

Cloud provider constants.

func GetProvider 

func GetProvider(ip string) Provider

GetProvider returns the provider for the given IP, or empty string if not found.

func GetProviderAddr 

func GetProviderAddr(addr netip.Addr) Provider

GetProviderAddr returns the provider for the given IP address.

func (Provider) String 

func (p Provider) String() string

String returns the provider name.

type VersionInfo 

type VersionInfo = source.VersionInfo

VersionInfo contains metadata about the data version. This is a re-export of the internal type for public use.

func CheckUpdate 

func CheckUpdate(ctx context.Context) (bool, *VersionInfo, error)

CheckUpdate checks if a new version is available using the default detector.

Source Files

View all Source files

Directories

Path Synopsis
Package main demonstrates the usage of the go-cloudip library.
 Package main demonstrates the usage of the go-cloudip library.
internal
source
Package source provides data loading functionality for cloudip.
 Package source provides data loading functionality for cloudip.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.