GlobalPing.cfc

A ColdFusion/CFML wrapper for the globalping CLI. Runs network measurements (ping, DNS, HTTP, traceroute, MTR) from probes around the world and returns typed structs.

Requirements

• ColdFusion 2016+ or Lucee 5.4+
• globalping CLI installed on the server
• Optional: a globalping API token for higher rate limits

Installation

Copy GlobalPing.cfc into your project. No external dependencies.

Initialization

gp = new GlobalPing(
    exePath = "C:\tools\globalping.exe",  // required: full path to the CLI binary
    token   = "",                          // optional: API token (injected via env var)
    tempDir = getTempDirectory(),          // optional: dir for temp token scripts
    timeout = 30                           // optional: process timeout in seconds
);

Parameter	Type	Default	Description
exePath	string	required	Full path to the globalping CLI binary
token	string	""	API token for authenticated requests
tempDir	string	getTempDirectory()	Directory for temporary token wrapper scripts
timeout	numeric	30	Seconds to wait for the CLI process to finish

Return Envelope

All methods return a struct with at minimum:

Key	Type	Description
success	boolean	true when the command succeeded
error	string	Error message; empty on success
raw	string	Raw CLI output

Measurement methods also include:

Key	Type	Description
id	string	Measurement ID
type	string	Measurement type (e.g. ping)
status	string	Measurement status (e.g. finished)
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last-updated timestamp
target	string	Target hostname or IP
probesCount	int	Number of probes used
shareUrl	string	Share URL (present when --share was requested)
results	array	Per-probe result structs (see per-method details)

---

Methods

ping()

result = gp.ping(
    target   = "8.8.8.8",     // required
    from     = "world",        // probe location filter
    limit    = 1,              // number of probes
    packets  = 3,              // ping packets per probe
    protocol = "ICMP",         // ICMP | TCP | UDP
    ipv4     = false,
    ipv6     = false,
    latency  = false,          // use --latency (plain-text summary)
    share    = false
);

result.results — array of:

{
    probe:  { continent, region, country, state, city, asn, latitude, longitude, network, tags },
    result: {
        status, resolvedAddress, resolvedHostname, rawOutput,
        timings: [ { ttl, rtt } ],
        stats:   { min, max, avg, total, loss, rcv, drop }
    }
}

When latency=true, returns a simplified struct:

{
    success, error, raw,
    results: [ { probe, min, max, avg } ]
}

---

dns()

result = gp.dns(
    target   = "google.com",
    from     = "world",
    limit    = 1,
    type     = "A",            // A | AAAA | CNAME | MX | NS | TXT | SOA | PTR | CAA | DS | DNSKEY | NSEC | NSEC3 | RRSIG | TLSA
    protocol = "UDP",          // UDP | TCP
    port     = 53,
    resolver = "",             // custom resolver IP/hostname
    trace    = false,
    ipv4     = false,
    ipv6     = false,
    latency  = false,
    share    = false
);

result.results — array of:

{
    probe:  { ... },
    result: {
        status, rawOutput, statusCode, statusCodeName, resolver,
        timings: { total },
        answers: [ { name, type, ttl, class, value } ]
    }
}

---

http()

result = gp.http(
    target   = "google.com",
    from     = "world",
    limit    = 1,
    method   = "HEAD",         // HEAD | GET | OPTIONS
    protocol = "HTTPS",        // HTTP | HTTPS | HTTP2
    port     = 443,
    path     = "/",
    query    = "",
    host     = "",
    resolver = "",
    full     = false,          // include response body
    headers  = [],             // array of "Name: Value" strings
    ipv4     = false,
    ipv6     = false,
    latency  = false,
    share    = false
);

result.results — array of:

{
    probe:  { ... },
    result: {
        status, resolvedAddress, statusCode, statusCodeName, truncated,
        rawOutput, rawHeaders, rawBody,
        headers:  { headerName: value },
        timings:  { total, dns, tcp, tls, firstByte, download },
        tls:      { authorized, protocol, cipherName, createdAt, expiresAt,
                    keyType, keyBits, serialNumber, fingerprint256, publicKey,
                    issuer: { C, O, CN }, subject: { CN, alt } }
    }
}

---

traceroute()

result = gp.traceroute(
    target   = "8.8.8.8",
    from     = "world",
    limit    = 1,
    protocol = "ICMP",         // ICMP | TCP | UDP
    ipv4     = false,
    ipv6     = false,
    share    = false
);

Note: latency=true is not supported for traceroute and will return success=false.

result.results — array of:

{
    probe:  { ... },
    result: {
        status, resolvedAddress, resolvedHostname, rawOutput,
        hops: [ { resolvedHostname, resolvedAddress, timings: [ { rtt } ] } ]
    }
}

---

mtr()

result = gp.mtr(
    target   = "8.8.8.8",
    from     = "world",
    limit    = 1,
    packets  = 3,
    protocol = "ICMP",         // ICMP | TCP | UDP
    ipv4     = false,
    ipv6     = false,
    share    = false
);

Note: latency=true is not supported for mtr and will return success=false.

result.results — array of:

{
    probe:  { ... },
    result: {
        status, resolvedAddress, resolvedHostname, rawOutput,
        hops: [
            {
                resolvedAddress, resolvedHostname,
                asn:     [ int ],
                timings: [ { rtt } ],
                stats:   { min, max, avg, total, loss, rcv, drop, stDev, jMin, jMax, jAvg }
            }
        ]
    }
}

---

limits()

Returns API usage limits for the configured token (or anonymous if no token).

result = gp.limits();

Return struct:

{
    success:        boolean,
    error:          string,
    raw:            string,
    authentication: string,   // e.g. "API token (pro)"
    measurements: {
        testsPerHour:    int,
        consumed:        int,
        remaining:       int,
        resetsInMinutes: int
    }
}

---

Probe Location Filter

The from parameter accepts:

• "world" — any available probe
• Country name or code: "US", "Germany"
• City: "New York", "London"
• Continent: "Europe", "NA"
• ASN: "AS15169"
• Network name: "Cloudflare"
• Magic keyword: "cdn", "eyeball", etc.
• Comma-separated list: "US,Germany,Japan"

Examples

Basic ping

gp     = new GlobalPing( exePath="/usr/local/bin/globalping" );
result = gp.ping( target="cloudflare.com", from="Europe", limit=3 );

if ( result.success ) {
    for ( var r in result.results ) {
        writeOutput( r.probe.city & ": avg=" & r.result.stats.avg & "ms" & "<br>" );
    }
}

DNS lookup with custom type

result = gp.dns( target="example.com", type="MX", limit=3 );

for ( var r in result.results ) {
    for ( var answer in r.result.answers ) {
        writeOutput( answer.value & "<br>" );
    }
}

HTTP check with latency summary

result = gp.http( target="example.com", method="GET", limit=5, latency=true );

for ( var r in result.results ) {
    writeOutput( r.probe & ": " & r.avg & "ms avg<br>" );
}

Ping latency summary (fast mode)

result = gp.ping( target="8.8.8.8", from="world", limit=5, latency=true );

for ( var r in result.results ) {
    writeOutput( r.probe & " min=#r.min#ms max=#r.max#ms avg=#r.avg#ms<br>" );
}

Check API limits

gp     = new GlobalPing( exePath="/usr/local/bin/globalping", token="your-token-here" );
result = gp.limits();

writeOutput( "Remaining: " & result.measurements.remaining & " tests" );

Error Handling

Always check result.success before accessing result data:

result = gp.ping( target="8.8.8.8" );

if ( !result.success ) {
    writeOutput( "Error: " & result.error );
    return;
}

// safe to use result.results here

Token Security

When a token is provided, GlobalPing.cfc writes a temporary script file (.bat on Windows, .sh on Unix) that sets GLOBALPING_TOKEN as an environment variable before invoking the CLI. The script is deleted in a finally block after execution, whether it succeeds or throws.

The token is never passed as a command-line argument and does not appear in process listings.