data

Documentation

Overview

Package data contains definitions for NS1 metadata/sources/feeds/etc.

Index

• func FormatInterface(i interface{}) string
• func ParseType(s string) interface{}
• func ToCamel(s string) string
• type Config
• type Destination
  • func NewDestination() *Destination
• type Feed
  • func NewFeed(name string, cfg Config) *Feed
• type FeedPtr
• type Meta
  • func MetaFromMap(m map[string]interface{}) *Meta
  • func (meta *Meta) StringMap() map[string]interface{}
  • func (meta *Meta) Validate() (errs []error)
• type PulsarMeta
• type Region
• type Regions
• type Source
  • func NewSource(name string, t string) *Source

Examples

• Feed
• Meta
• Regions
• Source

Functions

func FormatInterface

func FormatInterface(i interface{}) string

FormatInterface takes an interface of types: string, bool, int, float64, []string, map[string]interface{} and FeedPtr, and returns a string representation of said interface

func ParseType

func ParseType(s string) interface{}

ParseType returns an interface containing a string, bool, int, float64, []string, or FeedPtr float64 values with no decimal may be returned as integers, but that should be ok because the api won't know the difference when it's json encoded

func ToCamel

func ToCamel(s string) string

ToCamel converts a string to CamelCase

Types

type Config

type Config map[string]interface{}

Config is a flat mapping where values are simple (no slices/maps).

type Destination

type Destination struct {
	ID string `json:"destid"`

	// All destinations must point to a record.
	RecordID string `json:"record"`

	// Type is the 'level' at which to apply the filters(on the targeted record).
	// Options:
	//   - answer (highest precedence)
	//   - region
	//   - record (lowest precendence)
	Type string `json:"desttype"`

	SourceID string `json:"-"`
}

Destination is the target resource the receives data from a feed/source.

func NewDestination

func NewDestination() *Destination

NewDestination returns an empty feed destination.

type Feed

type Feed struct {
	ID     string `json:"id,omitempty"`
	Name   string `json:"name"`
	Config Config `json:"config,omitempty"`
	Data   Meta   `json:"data,omitempty"`

	Destinations []Destination `json:"destinations"`

	SourceID string
}

Feed wraps an NS1 /data/feeds resource

Example

package main

import (
	"fmt"

	"gopkg.in/ns1/ns1-go.v2/rest/model/data"
)

func main() {

	// Construct the london data feed.
	feed := data.NewFeed(
		"London Feed",
		data.Config{"label": "London-UK"})
	fmt.Println(feed.ID) // will be empty string
	fmt.Println(feed.Name)
	fmt.Println(feed.Config)
}

Output:

London Feed
map[label:London-UK]

func NewFeed

func NewFeed(name string, cfg Config) *Feed

NewFeed returns a data feed with given name and config.

type FeedPtr

type FeedPtr struct {
	FeedID string `json:"feed,omitempty"`
}

FeedPtr represents the dynamic metadata value in which a feed is providing the value.

type Meta

type Meta struct {

	// Indicates whether or not entity is considered 'up'
	// bool or FeedPtr.
	Up interface{} `json:"up,omitempty"`

	// Indicates the number of active connections.
	// Values must be positive.
	// int or FeedPtr.
	Connections interface{} `json:"connections,omitempty"`

	// Indicates the number of active requests (HTTP or otherwise).
	// Values must be positive.
	// int or FeedPtr.
	Requests interface{} `json:"requests,omitempty"`

	// Indicates the "load average".
	// Values must be positive, and will be rounded to the nearest tenth.
	// float64 or FeedPtr.
	LoadAvg interface{} `json:"loadavg,omitempty"`

	// The Job ID of a Pulsar telemetry gathering job and associated metadata.
	// list of PulsarMeta
	Pulsar interface{} `json:"pulsar,omitempty"`

	// Must be between -180.0 and +180.0 where negative
	// indicates South and positive indicates North.
	// e.g., the longitude of the datacenter where a server resides.
	// float64 or FeedPtr.
	Latitude interface{} `json:"latitude,omitempty"`

	// Must be between -180.0 and +180.0 where negative
	// indicates West and positive indicates East.
	// e.g., the longitude of the datacenter where a server resides.
	// float64 or FeedPtr.
	Longitude interface{} `json:"longitude,omitempty"`

	// Valid geographic regions are: 'US-EAST', 'US-CENTRAL', 'US-WEST',
	// 'EUROPE', 'ASIAPAC', 'SOUTH-AMERICA', 'AFRICA'.
	// e.g., the rough geographic location of the Datacenter where a server resides.
	// []string or FeedPtr.
	Georegion interface{} `json:"georegion,omitempty"`

	// Countr(ies) must be specified as ISO3166 2-character country code(s).
	// []string or FeedPtr.
	Country interface{} `json:"country,omitempty"`

	// State(s) must be specified as standard 2-character state code(s).
	// []string or FeedPtr.
	USState interface{} `json:"us_state,omitempty"`

	// Canadian Province(s) must be specified as standard 2-character province
	// code(s).
	// []string or FeedPtr.
	CAProvince interface{} `json:"ca_province,omitempty"`

	// Notes to indicate any necessary details for operators.
	// Up to 256 characters in length.
	// string or FeedPtr.
	Note interface{} `json:"note,omitempty"`

	// IP (v4 and v6) prefixes in CIDR format ("a.b.c.d/mask").
	// May include up to 1000 prefixes.
	// e.g., "1.2.3.4/24"
	// []string or FeedPtr.
	IPPrefixes interface{} `json:"ip_prefixes,omitempty"`

	// Autonomous System (AS) number(s).
	// May include up to 1000 AS numbers.
	// []string or FeedPtr.
	ASN interface{} `json:"asn,omitempty"`

	// Indicates the "priority tier".
	// Lower values indicate higher priority.
	// Values must be positive.
	// int or FeedPtr.
	Priority interface{} `json:"priority,omitempty"`

	// Indicates a weight.
	// Filters that use weights normalize them.
	// Any positive values are allowed.
	// Values between 0 and 100 are recommended for simplicity's sake.
	// float64 or FeedPtr.
	Weight interface{} `json:"weight,omitempty"`

	// Indicates a cost.
	// Filters that use costs normalize them.
	// Any positive values are allowed.
	// float64 or FeedPtr.
	Cost interface{} `json:"cost,omitempty"`

	// Indicates a "low watermark" to use for load shedding.
	// The value should depend on the metric used to determine
	// load (e.g., loadavg, connections, etc).
	// int or FeedPtr.
	LowWatermark interface{} `json:"low_watermark,omitempty"`

	// Indicates a "high watermark" to use for load shedding.
	// The value should depend on the metric used to determine
	// load (e.g., loadavg, connections, etc).
	// int or FeedPtr.
	HighWatermark interface{} `json:"high_watermark,omitempty"`

	// subdivisions must follow the ISO-3166-2 code for a country and subdivisions
	// map[string]interface{} or FeedPtr.
	Subdivisions interface{} `json:"subdivisions,omitempty"`

	AdditionalMetadata interface{} `json:"additional_metadata,omitempty"`
}

Meta contains information on an entity's metadata table. Metadata key/value pairs are used by a record's filter pipeline during a dns query. All values can be a feed id as well, indicating real-time updates of these values. Structure/Precedence of metadata tables:

• Record
• Meta <- lowest precedence in filter
• Region(s)
• Meta <- middle precedence in filter chain
• ...
• Answer(s)
• Meta <- highest precedence in filter chain
• ...
• ...

Example

package main

import (
	"fmt"

	"gopkg.in/ns1/ns1-go.v2/rest/model/data"
)

func main() {
	feedID := "feed_id"

	meta := data.Meta{}
	meta.Priority = 1
	meta.Up = data.FeedPtr{FeedID: feedID}
	fmt.Println(meta.Connections) // will be nil
	fmt.Println(meta.Priority)
	fmt.Println(meta.Up)
}

Output:

<nil>
1
{feed_id}

func MetaFromMap

func MetaFromMap(m map[string]interface{}) *Meta

MetaFromMap creates a *Meta and uses reflection to set fields from a map. This will panic if a value for a key is not a string. This it to ensure compatibility with terraform

func (*Meta) StringMap

func (meta *Meta) StringMap() map[string]interface{}

StringMap returns a map[string]interface{} representation of metadata (for use with terraform in nested structures)

func (*Meta) Validate

func (meta *Meta) Validate() (errs []error)

Validate validates metadata fields and returns a list of errors if any are found

type PulsarMeta

type PulsarMeta struct {
	JobID     string  `json:"job_id,omitempty"`
	Bias      string  `json:"bias,omitempty"`
	A5MCutoff float64 `json:"a5m_cutoff,omitempty"`
}

PulsarMeta is currently only used for validation

type Region

type Region struct {
	Meta Meta `json:"meta,omitempty"`
}

Region is a metadata table with a name/key. Can be thought of as metadata groupings.

type Regions

type Regions map[string]Region

Regions is simply a mapping of Regions inside a record.

Example

package main

import (
	"fmt"

	"gopkg.in/ns1/ns1-go.v2/rest/model/data"
)

func main() {
	feedPtr := data.FeedPtr{FeedID: "feed_id"}

	regions := data.Regions{}
	// Set a regions' 'up' metavalue to false('down').
	regions["some_region"] = data.Region{
		Meta: data.Meta{Up: false},
	}
	// Set a regions' 'connections' metavalue to receive from a feed.
	regions["other_region"] = data.Region{
		Meta: data.Meta{Connections: feedPtr},
	}
	fmt.Println(regions["some_region"].Meta.Up)
	fmt.Println(regions["some_region"].Meta.Priority)
	fmt.Println(regions["other_region"].Meta.Connections)
	fmt.Println(regions["other_region"].Meta.Priority)
}

Output:

false
<nil>
{feed_id}
<nil>

type Source

type Source struct {
	ID string `json:"id,omitempty"`

	// Human readable name of the source.
	Name string `json:"name"`

	Type   string `json:"sourcetype"`
	Config Config `json:"config,omitempty"`
	Status string `json:"status,omitempty"`

	Feeds []*Feed `json:"feeds,omitempty"`
}

Source wraps an NS1 /data/sources resource

Example

package main

import (
	"fmt"

	"gopkg.in/ns1/ns1-go.v2/rest/model/data"
)

func main() {
	// Construct an NSONE API data source.
	source := data.NewSource("my api source", "nsone_v1")
	fmt.Println(source.ID) // will be empty string
	fmt.Println(source.Name)
	fmt.Println(source.Type)
}

Output:

my api source
nsone_v1

func NewSource

func NewSource(name string, t string) *Source

NewSource takes a name and type t.