ripeatlas

package module
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Nov 16, 2022 License: MIT Imports: 12 Imported by: 10

README

Go bindings for RIPE Atlas API

GoDoc

About

Go bindings for the RIPE Atlas API to retrieve measurements and other data, can read from JSON files or use the REST API. Will decode the data into Go objects and have helper functions to easily access the data within.

Atlaser

Atlaser is the interface to access RIPE Atlas and there are a few different ways to do so:

  • To read JSON files see File and examples/reader/main.go.
  • To use REST API see Http and examples/reader/main.go.
  • To use Streaming API see Stream and examples/streamer/main.go.

REST API

Implementation status of API calls described by https://atlas.ripe.net/docs/api/v2/reference/ .

anchor-measurements
anchors
credits
keys
measurements
Call Status Func
/api/v2/measurements/ HTTP only Atlaser.Measurements()
/api/v2/measurements/{pk} HTTP only Atlaser.Measurements()
/api/v2/measurements/{pk}/latest/ Done Atlaser.MeasurementLatest()
/api/v2/measurements/{pk}/results/ Done Atlaser.MeasurementResults()
participation-requests
probes
Call Status Func
/api/v2/probes/ HTTP only Atlaser.Probes()
/api/v2/probes/{pk} HTTP only Atlaser.Probes()

Objects

Implementation status of objects (by type) decribed by https://atlas.ripe.net/docs/data_struct/ .

Type Fireware Status
dns 4610 to 4760 Done
ping 4610 to 4760 Done
traceroute 4610 to 4760 Done
http 4610 to 4760 Done
ntp 4610 to 4760 Done
sslcert 4610 to 4760 Done
wifi 4610 to 4760 Done (undocumented by RIPE)

Usage

See or test more complete examples in the examples directory.

import (
    "fmt"
    "github.com/DNS-OARC/ripeatlas"
)

// Read Atlas results from a file
a := ripeatlas.Atlaser(ripeatlas.NewFile())
c, err := a.MeasurementResults(ripeatlas.Params{"file": name})
if err != nil {
    ...
}
for r := range c {
    if r.ParseError != nil {
        ...
    }
    fmt.Printf("%d %s\n", r.MsmId(), r.Type())
}

// Read Atlas results using REST API
a := ripeatlas.Atlaser(ripeatlas.NewHttp())
c, err := a.MeasurementResults(ripeatlas.Params{"pk": id})
if err != nil {
    ...
}
for r := range c {
    if r.ParseError != nil {
        ...
    }
    fmt.Printf("%d %s\n", r.MsmId(), r.Type())
}

// Read DNS measurements using Streaming API
a := ripeatlas.Atlaser(ripeatlas.NewStream())
c, err := a.MeasurementResults(ripeatlas.Params{"type": "dns"})
if err != nil {
    ...
}
for r := range c {
    if r.ParseError != nil {
        ...
    }
    fmt.Printf("%d %s\n", r.MsmId(), r.Type())
}

Author(s)

Jerry Lundström jerry@dns-oarc.net

License

MIT License

Copyright (c) 2022 OARC, Inc.

Documentation

Overview

Package ripeatlas implements bindings for RIPE Atlas.

The Atlaser is the interface to access RIPE Atlas and there are a few different ways to do so, for example read measurement results from a JSON file: 

a := ripeatlas.Atlaser(ripeatlas.NewFile())
c, err := a.MeasurementResults(ripeatlas.Params{"file": name})
if err != nil {
    ...
}
for r := range c {
    if r.ParseError != nil {
        ...
    }
    fmt.Printf("%d %s\n", r.MsmId(), r.Type())
}

See File for file access, Http for REST API access and Stream for Streaming API access.

Index

Constants

View Source 
const (
	MeasurementsUrl = "https://atlas.ripe.net/api/v2/measurements"
	ProbesUrl       = "https://atlas.ripe.net/api/v2/probes"
)
View Source 
const (
	StreamUrl = "wss://atlas-stream.ripe.net:443/stream/socket.io/?EIO=3&transport=websocket"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Atlaser 

type Atlaser interface {
	Measurements(p Params) (<-chan *Measurement, error)
	MeasurementLatest(p Params) (<-chan *measurement.Result, error)
	MeasurementResults(p Params) (<-chan *measurement.Result, error)
	Probes(p Params) (<-chan *request.Probe, error)
}

Atlaser is the interface for accessing RIPE Atlas, designed after the REST API (https://atlas.ripe.net/docs/api/v2/reference/).

type File 

type File struct {
}

A File reads RIPE Atlas data from JSON files.

func NewFile 

func NewFile() *File

NewFile returns a new Atlaser for reading from a JSON file.

func (*File) MeasurementLatest 

func (f *File) MeasurementLatest(p Params) (<-chan *measurement.Result, error)

Since File can not distinguish what is the latest results, MeasurementLatest will just call MeasurementResults.

func (*File) MeasurementResults 

func (f *File) MeasurementResults(p Params) (<-chan *measurement.Result, error)

MeasurementResults reads the measurement results, as described by the Params, and sends them to the returned channel.

Params available are:

"file": string - The JSON file to read from (required).

"fragmented": bool - If true, JSON is in a fragmented/stream format.

func (*File) Measurements 

func (f *File) Measurements(p Params) (<-chan *Measurement, error)

func (*File) Probes 

func (f *File) Probes(p Params) (<-chan *request.Probe, error)

type Http 

type Http struct {
}

A Http reads RIPE Atlas data from the RIPE Atlas REST API.

func NewHttp 

func NewHttp() *Http

NewHttp returns a new Atlaser for reading from the RIPE Atlas REST API.

func (*Http) MeasurementLatest 

func (h *Http) MeasurementLatest(p Params) (<-chan *measurement.Result, error)

MeasurementLatest gets the latest measurement results, as described by the Params, and sends them to the returned channel.

Params available are:

"pk": string - The measurement id to read results from (required).

"fragmented": bool - If true, use the fragmented/stream format when reading.

func (*Http) MeasurementResults 

func (h *Http) MeasurementResults(p Params) (<-chan *measurement.Result, error)

MeasurementResults gets the measurement results, as described by the Params, and sends them to the returned channel.

Params available are:

"pk": string - The measurement id to read results from (required).

"start": int64 - Get the results starting at the given UNIX timestamp.

"stop": int64 - Get the results up to the given UNIX timestamp.

"probe_ids": none - Unimplemented

"anchors-only": none - Unimplemented

"public-only": none - Unimplemented

"fragmented": bool - If true, use the fragmented/stream format when reading.

func (*Http) Measurements 

func (h *Http) Measurements(p Params) (<-chan *Measurement, error)

Measurements gets the metadata of measurements, as described by the Params, and sends them to the returned channel.

Params available are:

"page": int64 - The pagination page to read (default 1).

"pk": string - The measurement id to read a specific measurement.

func (*Http) Probes 

func (h *Http) Probes(p Params) (<-chan *request.Probe, error)

Probes gets the metadata of probes, as described by the Params, and sends them to the returned channel.

Params available are:

"page": int64 - The pagination page to read (default 1).

"pk": string - The probe id to read a specific probe.

type Measurement 

type Measurement struct {
	ParseError error
	// contains filtered or unexported fields
}

func (*Measurement) Af 

func (m *Measurement) Af() int

[core] [Not for wifi] IPv4 of IPv6 Address family of the measurement. [wifi] IPv4 of IPv6 Address family of the measurement.

func (*Measurement) AnonymousIdentity 

func (m *Measurement) AnonymousIdentity() string

[wifi] Username used for outer connection. If omitted the `identity` field is used for the outer connection.

func (*Measurement) Cert 

func (m *Measurement) Cert() string

[wifi] Certificate in PEM format.

func (*Measurement) CreationTime 

func (m *Measurement) CreationTime() int

[core] The creation date and time of the measurement (Defaults to unix timestamp format).

func (*Measurement) Description 

func (m *Measurement) Description() string

[core] User-defined description of the measurement.

func (*Measurement) DestinationOptionSize 

func (m *Measurement) DestinationOptionSize() int

[traceroute] Size of an IPv6 destination option header filled with NOPs.

func (*Measurement) DontFragment 

func (m *Measurement) DontFragment() bool

[traceroute] Do not fragment outgoing packets.

func (*Measurement) DuplicateTimeout 

func (m *Measurement) DuplicateTimeout() int

[traceroute] Time to wait (in milliseconds) for a duplicate response after receiving the first response.

func (*Measurement) Eap 

func (m *Measurement) Eap() string

[wifi] Extensible Authentication Protocol type. Currently only `TTLS` is available.

func (*Measurement) ExtendedTiming 

func (m *Measurement) ExtendedTiming() bool

http Enable time-to-resolve, time-to-connect and time-to-first-byte measurements.

func (*Measurement) ExtraWait 

func (m *Measurement) ExtraWait() int

[wifi] Wait this amount of time before executing measurement commands..

func (*Measurement) FirstHop 

func (m *Measurement) FirstHop() int

[traceroute] TTL (time to live) of the first hop.

func (*Measurement) Group 

func (m *Measurement) Group() string

[core] The API URL of the measurement group..

func (*Measurement) GroupId 

func (m *Measurement) GroupId() int

[core] The ID of the measurement group. This ID references a measurement acting as group master.

func (*Measurement) HeaderBytes 

func (m *Measurement) HeaderBytes() int

http Maximum number of bytes in the reponse header, defaults to 0.

func (*Measurement) HopByHopOptionSize 

func (m *Measurement) HopByHopOptionSize() int

[traceroute] Size of an IPv6 hop-by-hop option header filled with NOPs.

func (*Measurement) Hostname 

func (m *Measurement) Hostname() string

[sslcert] Server Name Indication (SNI) hostname.

func (*Measurement) Id 

func (m *Measurement) Id() int

[core] .

func (*Measurement) Identity 

func (m *Measurement) Identity() string

[wifi] Username used for wifi connection. Used for both outer and inner connection if anonymous_identity is omitted.

func (*Measurement) InWifiGroup 

func (m *Measurement) InWifiGroup() bool

[core] Flag indicating this measurement belongs to a wifi measurement group.

func (*Measurement) IncludeAbuf 

func (m *Measurement) IncludeAbuf() bool

[dns] include the raw DNS answer data in the result. Defaults to true.

func (*Measurement) IncludeProbeId 

func (m *Measurement) IncludeProbeId() bool

[ping] Include the probe ID (encoded as ASCII digits) as part of the payload.

func (*Measurement) IncludeQbuf 

func (m *Measurement) IncludeQbuf() bool

[dns] include the raw DNS query data in the result. Defaults to false.

func (*Measurement) Interval 

func (m *Measurement) Interval() int

[dns] Interval between samples from a single probe. Defaults to 240 seconds.. http Interval between samples from a single probe. Defaults to 1800 seconds.. [ntp] Interval between samples from a single probe. Defaults to 1800 seconds.. [ping] Interval between samples from a single probe. Defaults to 240 seconds.. [sslcert] Interval between samples from a single probe. Defaults to 900 seconds.. [traceroute] Interval between samples from a single probe. Defaults to 900 seconds.. [wifi] Interval between samples from a single probe. Defaults to 900 seconds.

func (*Measurement) Ipv4 

func (m *Measurement) Ipv4() bool

[wifi] Flag indicating IPv4 measurements are attempted in this group.

func (*Measurement) Ipv6 

func (m *Measurement) Ipv6() bool

[wifi] Flag indicating IPv6 measurements are attempted in this group.

func (*Measurement) IsAllScheduled 

func (m *Measurement) IsAllScheduled() bool

[core] Returns true if all probe requests have made it through the scheduling process..

func (*Measurement) IsOneoff 

func (m *Measurement) IsOneoff() bool

[core] Flag indicating this is a one-off measurement.

func (*Measurement) IsPublic 

func (m *Measurement) IsPublic() bool

[core] Flag indicating this measurement is a publicly available.

func (*Measurement) KeyMgmt 

func (m *Measurement) KeyMgmt() string

[wifi] Authentication mechanism used for the wifi connection. For WPA-PSK `psk` field is also required,for WPA-EAP `eap` and `password` fields are required.

func (*Measurement) MaxBytesRead 

func (m *Measurement) MaxBytesRead() int

http .

func (*Measurement) MaxHops 

func (m *Measurement) MaxHops() int

[traceroute] Traceroute measurement stops after the hop at which the TTL reaches this value.

func (*Measurement) Method 

func (m *Measurement) Method() string

http http verb of the measurement request.

func (*Measurement) MoreExtendedTiming 

func (m *Measurement) MoreExtendedTiming() bool

http Include fields added by extended_timing and adds readtiming which reports for each read system call when it happened and how much data was delivered.

func (*Measurement) PacketInterval 

func (m *Measurement) PacketInterval() int

[ping] Time between packets in milliseconds. Value must be between 2 and 300000.

func (*Measurement) Packets 

func (m *Measurement) Packets() int

[ntp] The number of packets send in a measurement execution. Value must be between 1 and 16. Default is 3. [ping] The number of packets send in a measurement execution. Value must be between 1 and 16. Default is 3. [traceroute] The number of packets send in a measurement execution. Value must be between 1 and 16. Default is 3.

func (*Measurement) Paris 

func (m *Measurement) Paris() int

[traceroute] The number of paris traceroute variations to try. Zero disables paris traceroute. Value must be between 0 and 64.

func (*Measurement) ParticipantCount 

func (m *Measurement) ParticipantCount() int

[core] Number of participating probes.

func (*Measurement) ParticipationRequests 

func (m *Measurement) ParticipationRequests() []*measurement.ProbeSource

[core] .

func (*Measurement) Path 

func (m *Measurement) Path() string

http Path of the requested URL.

func (*Measurement) Phase2 

func (m *Measurement) Phase2() string

[wifi] Connection and Authentication directives for the inner connection. Only used for WPA-EAP. Currently only EAP-MSCHAPv2 is available.

func (*Measurement) Port 

func (m *Measurement) Port() int

http The target port number Defaults to 80. [sslcert] The target port number. Defaults to 443. [traceroute] The target port number (TCP only). Defaults to 80.

func (*Measurement) PrependProbeId 

func (m *Measurement) PrependProbeId() bool

[dns] Each probe prepends its probe number and a timestamp to the DNS query argument to make it unique.

func (*Measurement) ProbeSources 

func (m *Measurement) ProbeSources() []*measurement.ProbeSource

[core] .

func (*Measurement) Probes 

func (m *Measurement) Probes() []*measurement.Probe

[core] probes involved in this measurement.

func (*Measurement) ProbesRequested 

func (m *Measurement) ProbesRequested() int

[core] Number of probes requested, but not necessarily granted to this measurement.

func (*Measurement) ProbesScheduled 

func (m *Measurement) ProbesScheduled() int

[core] Number of probes actually scheduled for this measurement.

func (*Measurement) Protocol 

func (m *Measurement) Protocol() string

[dns] Protocol used in measurement. Defaults to UDP. [traceroute] Protocol used in measurement.

func (*Measurement) QueryArgument 

func (m *Measurement) QueryArgument() string

[dns] The `argument` part of the query used in the measurement.

func (*Measurement) QueryClass 

func (m *Measurement) QueryClass() string

[dns] The `class` part of the query used in the measurement.

func (*Measurement) QueryString 

func (m *Measurement) QueryString() string

http Optional query parameters of the requested URL.

func (*Measurement) QueryType 

func (m *Measurement) QueryType() string

[dns] The `type` part of the query used in the measurement.

func (*Measurement) ResolveOnProbe 

func (m *Measurement) ResolveOnProbe() bool

[core] Flag that, when set to true, indicates that a name should be resolved (using DNS) on the probe. Otherwise it will be resolved on the RIPE Atlas servers.

func (*Measurement) ResolvedIps 

func (m *Measurement) ResolvedIps() []string

[core] The list of IP addresses returned for the fqdn in the `target` field by the backend infra-structure resolvers.

func (*Measurement) ResponseTimeout 

func (m *Measurement) ResponseTimeout() int

[traceroute] Response timeout for one packet.

func (*Measurement) Result 

func (m *Measurement) Result() string

[core] The URL that contains the results of this measurement.

func (*Measurement) Retry 

func (m *Measurement) Retry() int

[dns] Number of times to retry.

func (*Measurement) Rssi 

func (m *Measurement) Rssi() bool

[wifi] Flag indicating that BSSID radio signal strength will be measured and stored.

func (*Measurement) SetCdBit 

func (m *Measurement) SetCdBit() bool

[dns] Flag indicating DNSSEC Checking Disabled (RFC4035) was set.

func (*Measurement) SetDoBit 

func (m *Measurement) SetDoBit() bool

[dns] Flag indicating DNSSEC OK (RFC3225) was set.

func (*Measurement) SetNsidBit 

func (m *Measurement) SetNsidBit() bool

[dns] Flag indicating Name Server Identifier (RFC5001) was set.

func (*Measurement) SetRdBit 

func (m *Measurement) SetRdBit() bool

[dns] Flag indicating Recursion Desired bit was set.

func (*Measurement) Size 

func (m *Measurement) Size() int

[ping] size of the data part of the packet, i.e. excluding any IP and ICMP headers. Value must be between 1 and 2048. [traceroute] size of the data part of the packet, i.e. excluding any IP, ICMP, UDP or TCP headers. Value must be between 0 and 2048.

func (*Measurement) Spread 

func (m *Measurement) Spread() int

[core] Distribution of probes' measurements throughout the interval (default is half the interval, maximum 400 seconds).

func (*Measurement) Ssid 

func (m *Measurement) Ssid() string

[wifi] Wifi SSID to connect to. Max. 32 characters.

func (*Measurement) StartTime 

func (m *Measurement) StartTime() int

[core] Configured start time (as a unix timestamp).

func (*Measurement) Status 

func (m *Measurement) Status() *measurement.MeasurementStatus

[core] Returns a JSON object containing `id` and `name` (0: Specified, 1: Scheduled, 2: Ongoing, 4: Stopped, 5: Forced to stop, 6: No suitable probes, 7: Failed, 8: Archived).

func (*Measurement) StopTime 

func (m *Measurement) StopTime() int

[core] Actual end time of measurement (as a unix timestamp).

func (*Measurement) TargetAsn 

func (m *Measurement) TargetAsn() int

[core] The ASN the IP the target is in.

func (*Measurement) TargetIp 

func (m *Measurement) TargetIp() string

[core] The IP Address of the target of the measurement.

func (*Measurement) Timeout 

func (m *Measurement) Timeout() int

[dns] Timeout in milliseconds (default: 5000). [ntp] Per packet timeout in milliseconds.

func (*Measurement) Type 

func (m *Measurement) Type() string

[core] Returns the type of the measurement.

func (*Measurement) UdpPayloadSize 

func (m *Measurement) UdpPayloadSize() int

[dns] Set the DNS0 option for UDP payload size to this value, between 512 and 4096.Defaults to 512).

func (*Measurement) UnmarshalJSON 

func (m *Measurement) UnmarshalJSON(b []byte) error

func (*Measurement) UseMacros 

func (m *Measurement) UseMacros() bool

[dns] Allow the use of $p (probe ID), $r (random 16-digit hex string) and $t (timestamp) in the query_argument.

func (*Measurement) UseProbeResolver 

func (m *Measurement) UseProbeResolver() bool

[dns] Send the DNS query to the probe's local resolvers (instead of an explicitly specified target).

func (*Measurement) UserAgent 

func (m *Measurement) UserAgent() string

http user agent header field sent in the http request. Always set to 'RIPE Atlas: https//atlas.ripe.net'.

func (*Measurement) Version 

func (m *Measurement) Version() string

http http version of measurement request.

type Params 

type Params map[string]interface{}

Params is used to give parameters to the different access methods.

type Stream 

type Stream struct {
}

A Stream reads RIPE Atlas data from the streaming API (https://atlas.ripe.net/docs/result-streaming/).

func NewStream 

func NewStream() *Stream

NewHttp returns a new Atlaser for reading from the RIPE Atlas streaming API.

func (*Stream) MeasurementLatest 

func (s *Stream) MeasurementLatest(p Params) (<-chan *measurement.Result, error)

MeasurementLatest streams the latest measurement results, as described by the Params, and sends them to the returned channel.

Params available are:

"msm": int - The measurement id to get results from.

"type": string - The measurement result type to stream.

"sourceAddress": none - Unimplemented

"sourcePrefix": none - Unimplemented

"destinationAddress": none - Unimplemented

"destinationPrefix": none - Unimplemented

"passThroughHost": none - Unimplemented

"passThroughPrefix": none - Unimplemented

"sendBacklog": none - Unimplemented

"buffering": none - Unimplemented

func (*Stream) MeasurementResults 

func (s *Stream) MeasurementResults(p Params) (<-chan *measurement.Result, error)

Since Stream streams the latest results (more or less, backlog sending is available), MeasurementResults will just call MeasurementLatest.

func (*Stream) Measurements 

func (s *Stream) Measurements(p Params) (<-chan *Measurement, error)

func (*Stream) Probes 

func (s *Stream) Probes(p Params) (<-chan *request.Probe, error)

Source Files

View all Source files

Directories

Path Synopsis
dns
http
ntp
ping
sslcert
traceroute
probe

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.