web

README

web

This package contains HTTP related configurations (Request, Client and HTTP structs) and functions to create http.Request and http.Client from them.

HTTP embeds both Request and Client.

Every module that collects metrics doing HTTP requests should use HTTP. It allows to have same set of user configurable options across all modules.

Configuration options

HTTP request options:

• url: the URL to access.
• username: the username for basic HTTP authentication.
• password: the password for basic HTTP authentication.
• proxy_username: the username for basic HTTP authentication of a user agent to a proxy server.
• proxy_password: the password for basic HTTP authentication of a user agent to a proxy server.
• body: the HTTP request body to be sent by the client.
• method: the HTTP method (GET, POST, PUT, etc.).
• headers: the HTTP request header fields to be sent by the client.

HTTP client options:

• timeout: the HTTP request time limit.
• not_follow_redirects: the policy for handling redirects.
• proxy_url: the URL of the proxy to use.
• tls_skip_verify: controls whether a client verifies the server's certificate chain and host name.
• tls_ca: certificate authority to use when verifying server certificates.
• tls_cert: tls certificate to use.
• tls_key: tls key to use.

Usage

Just make HTTP part of your module configuration.

package example

import "github.com/netdata/go.d.plugin/pkg/web"

type Config struct {
	web.HTTP `yaml:",inline"`
}

type Example struct {
	Config `yaml:",inline"`
}

func (e *Example) Init() bool {
	httpReq, err := web.NewHTTPRequest(e.Request)
	if err != nil {
		// ...
		return false
	}

	httpClient, err := web.NewHTTPClient(e.Client)
	if err != nil {
		// ...
		return false
	}

	// ...
	return true
}

Having HTTP embedded your configuration inherits all configuration options:

jobs:
  - name: name
    url: url
    username: username
    password: password
    proxy_url: proxy_url
    proxy_username: proxy_username
    proxy_password: proxy_password
    timeout: 1
    method: GET
    body: '{"key": "value"}'
    headers:
      X-API-Key: key
    not_follow_redirects: no
    tls_skip_verify: no
    tls_ca: path/to/ca.pem
    tls_cert: path/to/cert.pem
    tls_key: path/to/key.pem

Documentation

Overview

Package web contains HTTP request and client configurations. HTTP structure embeds both of them, and it's the only structure that intended to be used as part of a module's configuration. Every module that uses HTTP requests to collect metrics should use it. It allows to have same set of user configurable options across all modules.

Index

• Variables
• func NewHTTPClient(cfg Client) (*http.Client, error)
• func NewHTTPRequest(cfg Request) (*http.Request, error)
• type Client
• type Duration
  • func (d Duration) String() string
  • func (d *Duration) UnmarshalYAML(unmarshal func(interface{}) error) error
• type HTTP
• type Request
  • func (r Request) Copy() Request

Examples

• HTTP (Usage)

Variables

var ErrRedirectAttempted = errors.New("redirect")

ErrRedirectAttempted indicates that a redirect occurred.

Functions

func NewHTTPClient

func NewHTTPClient(cfg Client) (*http.Client, error)

NewHTTPClient returns a new *http.Client given a Client configuration and an error if any.

func NewHTTPRequest

func NewHTTPRequest(cfg Request) (*http.Request, error)

NewHTTPRequest returns a new *http.Requests given a Request configuration and an error if any.

Types

type Client

type Client struct {
	// Timeout specifies a time limit for requests made by this Client.
	// Default (zero value) is no timeout. Must be set before http.Client creation.
	Timeout Duration `yaml:"timeout"`

	// NotFollowRedirect specifies the policy for handling redirects.
	// Default (zero value) is std http package default policy (stop after 10 consecutive requests).
	NotFollowRedirect bool `yaml:"not_follow_redirects"`

	// ProxyURL specifies the URL of the proxy to use. An empty string means use the environment variables
	// HTTP_PROXY, HTTPS_PROXY and NO_PROXY (or the lowercase versions thereof) to get the URL.
	ProxyURL string `yaml:"proxy_url"`

	// TLSConfig specifies the TLS configuration.
	tlscfg.TLSConfig `yaml:",inline"`
}

Client is the configuration of the HTTP client. This structure is not intended to be used directly as part of a module's configuration. Supported configuration file formats: YAML.

type Duration

type Duration struct {
	Duration time.Duration
}

Duration is a time.Duration wrapper.

func (Duration) String

func (d Duration) String() string

func (*Duration) UnmarshalYAML

func (d *Duration) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML implements yaml.Unmarshaler.

type HTTP

type HTTP struct {
	Request `yaml:",inline"`
	Client  `yaml:",inline"`
}

HTTP is a struct with embedded Request and Client. This structure intended to be part of the module configuration. Supported configuration file formats: YAML.

Example (Usage)

// Just embed HTTP into your module structure.
// It allows you to have both Request and Client fields in the module configuration file.
type myModule struct {
	HTTP `yaml:",inline"`
}

var m myModule
_, _ = NewHTTPRequest(m.Request)
_, _ = NewHTTPClient(m.Client)

type Request

type Request struct {
	// URL specifies the URL to access.
	URL string `yaml:"url"`

	// Body specifies the HTTP request body to be sent by the client.
	Body string `yaml:"body"`

	// Method specifies the HTTP method (GET, POST, PUT, etc.). An empty string means GET.
	Method string `yaml:"method"`

	// Headers specifies the HTTP request header fields to be sent by the client.
	Headers map[string]string `yaml:"headers"`

	// Username specifies the username for basic HTTP authentication.
	Username string `yaml:"username"`

	// Password specifies the password for basic HTTP authentication.
	Password string `yaml:"password"`

	// ProxyUsername specifies the username for basic HTTP authentication.
	// It is used to authenticate a user agent to a proxy server.
	ProxyUsername string `yaml:"proxy_username"`

	// ProxyPassword specifies the password for basic HTTP authentication.
	// It is used to authenticate a user agent to a proxy server.
	ProxyPassword string `yaml:"proxy_password"`
}

Request is the configuration of the HTTP request. This structure is not intended to be used directly as part of a module's configuration. Supported configuration file formats: YAML.

func (Request) Copy

func (r Request) Copy() Request

Copy makes a full copy of the Request.