varnishclient

package module
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Aug 5, 2020 License: MIT Imports: 11 Imported by: 0

README

Go client for the Varnish administration port

This repository contains a client library that can be used to connect to the Varnish administration port (typically used by the varnishadm tool).

NOTE: Experimental. Use at own peril!

Installation

Install this library via go get:

$ go get github.com/martin-helmich/go-varnish-client

Usage

Establish a connection

First, connect to the administration port using the varnishclient.DialTCP method:

client, err := varnishclient.DialTCP(context.Background(), "127.0.0.1:6082")
if err != nil {
    panic(err)
}
Authenticate

You can then use the client.AuthenticationRequired() method to check if the Varnish server requires authentication. Then, use the client.Authenticate() method to perform the authentication:

secret, _ := ioutil.ReadFile("/etc/varnish/secret")

if client.AuthenticationRequired() {
    err := client.Authenticate(context.Background(), secret)
    if err != nil {
        panic(err)
    }
}
Define and update a new configuration
ctx := context.Background()

err := client.DefineInlineVCL(ctx, "my-new-config", vclCode, "warm")
if err != nil {
    panic(err)
}

err = client.UseVCL(ctx, "my-new-config")
if err != nil {
    panic(err)
}
Define timeouts/cancellations on operations

All operations accept a context.Context parameter that can be used for timeouts and/or cancellations:

ctx, cancel := context.WithTimeout(context.Background(), 1 * time.Second)
defer cancel()

err := client.DefineInlineVCL(ctx, "my-new-config", vclCode, "warm")
if err != nil {
    panic(err)
}

Documentation

Index

Examples

Constants

View Source 
const (
	ResponseSyntaxError            = 100
	ResponseUnknownCommand         = 101
	ResponseUnimplemented          = 102
	ResponseTooFewArguments        = 104
	ResponseTooManyArguments       = 105
	ResponseParams                 = 106
	ResponseAuthenticationRequired = 107
	ResponseOK                     = 200
	ResponseCant                   = 300
	ResponseComms                  = 400
	ResponseClose                  = 500
)

These constants define the usual response codes returned by the Varnish admin server.

Variables

This section is empty.

Functions

This section is empty.

Types

type Backend 

type Backend struct {
	Name string
}

Backend is a single item of the list returned by the `ListBackends` method

type BackendsResponse 

type BackendsResponse []Backend

BackendsResponse is the respose type of the `ListBackends` method

type Client 

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

Client contains the most common Varnish administration operations (and the necessary tools to build your own that are not yet implemented)

func DialTCP 

func DialTCP(ctx context.Context, address string) (*Client, error)

DialTCP connects to an existing Varnish administration port. This method does not perform authentication. Use the `Authenticate()` method for that.

func (*Client) AddLabelToVCL 

func (c *Client) AddLabelToVCL(ctx context.Context, label string, configname string) error

AddLabelToVCL adds a label to a configuration file. See https://varnish-cache.org/docs/trunk/reference/varnish-cli.html#vcl-label-label-configname

func (*Client) Authenticate 

func (c *Client) Authenticate(ctx context.Context, secret []byte) error

Authenticate authenticates the client with Varnish. This method only does something then the Varnish admin server actually requires authentication (you can test for that using the AuthenticationRequired method).

The "secret" parameter should be the binary content read from the Varnish secret file.

If you call this method then the server does not require authentication, it will simply do nothing and return "nil".

Example 
if client.AuthenticationRequired() {
	secret, err := ioutil.ReadFile("/etc/varnish/secret")
	if err != nil {
		panic(err)
	}

	if err := client.Authenticate(ctx, secret); err != nil {
		panic(err)
	}

	// You're authenticated. Yay!
}

Output:

func (*Client) AuthenticationRequired 

func (c *Client) AuthenticationRequired() bool

AuthenticationRequired tells you if the server requires the client to authenticate itself before doing anything.

If this returns "true", the next call should be to "Authenticate".

func (*Client) DefineInlineVCL 

func (c *Client) DefineInlineVCL(ctx context.Context, configname string, vcl []byte, mode VCLState) error

DefineInlineVCL compiles and loads a new VCL file with the file contents specified by the "vcl" parameter. See https://varnish-cache.org/docs/trunk/reference/varnish-cli.html#vcl-inline-configname-quoted-vclstring-auto-cold-warm

func (*Client) DiscardVCL 

func (c *Client) DiscardVCL(ctx context.Context, configname string) error

DiscardVCL unloads the VCL file specified by the given "configname". See https://varnish-cache.org/docs/trunk/reference/varnish-cli.html#vcl-discard-configname-label

func (*Client) GetParameter 

func (c *Client) GetParameter(ctx context.Context, name string) (*Parameter, error)

GetParameter returns a single parameter

func (*Client) ListBackends 

func (c *Client) ListBackends(ctx context.Context, pattern string) (BackendsResponse, error)

ListBackends returns the list of available backends. See https://varnish-cache.org/docs/trunk/reference/varnish-cli.html#backend-list-j-p-backend-pattern

func (*Client) ListParameters 

func (c *Client) ListParameters(ctx context.Context) (ParametersResponse, error)

ListParameters lists all Varnish parameters and their values. See https://varnish-cache.org/docs/trunk/reference/varnish-cli.html#param-show-l-j-param-changed

func (*Client) ListVCL 

func (c *Client) ListVCL(ctx context.Context) (VCLConfigsResponse, error)

ListVCL lists the compiled VCLs. See https://varnish-cache.org/docs/trunk/reference/varnish-cli.html#vcl-list-j

func (*Client) LoadVCL 

func (c *Client) LoadVCL(ctx context.Context, configname, filename string, mode VCLState) error

LoadVCL compiles and loads the VCL file from the given file. See https://varnish-cache.org/docs/trunk/reference/varnish-cli.html#vcl-load-configname-filename-auto-cold-warm

func (*Client) SetParameter 

func (c *Client) SetParameter(ctx context.Context, name, value string) error

SetParameter sets a parameter to the specified value. See https://varnish-cache.org/docs/trunk/reference/varnish-cli.html#param-set-param-value

func (*Client) SetVCLState 

func (c *Client) SetVCLState(ctx context.Context, configname string, state VCLState) error

SetVCLState can be used to force a loaded VCL file to a specific state. See https://varnish-cache.org/docs/trunk/reference/varnish-cli.html#vcl-state-configname-auto-cold-warm

Example 
if err := exampleClient.SetVCLState(ctx, "boot", VCLStateCold); err != nil {
	// handle error
}

Output:

func (*Client) UseVCL 

func (c *Client) UseVCL(ctx context.Context, configname string) error

UseVCL make Varnish switch to the specified configuration file immediately See https://varnish-cache.org/docs/trunk/reference/varnish-cli.html#vcl-use-configname-label

type ClientInterface 

type ClientInterface interface {
	AuthenticationRequired() bool
	Authenticate(ctx context.Context, secret []byte) error
	ListBackends(ctx context.Context, pattern string) (BackendsResponse, error)

	SetParameter(ctx context.Context, name, value string) error
	ListParameters(ctx context.Context) (ParametersResponse, error)

	DiscardVCL(ctx context.Context, configName string) error
	DefineInlineVCL(ctx context.Context, configName string, vcl []byte, mode VCLState) error
	AddLabelToVCL(ctx context.Context, label string, configName string) error
	ListVCL(ctx context.Context) (VCLConfigsResponse, error)
	LoadVCL(ctx context.Context, configName, filename string, mode VCLState) error
	UseVCL(ctx context.Context, configName string) error
	SetVCLState(ctx context.Context, configName string, state VCLState) error
}

ClientInterface describes the common methods offered by the Varnish client

type Parameter 

type Parameter struct {
	Name      string
	Value     string
	Unit      string
	IsDefault bool
}

Parameter is a single item of the list returned by the `ListParameters` method

type ParametersResponse 

type ParametersResponse []Parameter

ParametersResponse is the response type of the `ListParameters` method

type Request 

type Request struct {
	Method    string
	Arguments []string
}

Request contains the data sent to Varnish as a request

type Response 

type Response struct {
	Code int
	Body []byte
}

Response contains the data that was received from Varnish in response to a request

type Roundtrip 

type Roundtrip interface {
	ReadHello(ctx context.Context) (*Response, error)
	Execute(ctx context.Context, req *Request) (*Response, error)
}

Roundtrip defines the interface for sending requests to Varnish and receiving responses

type VCLConfig 

type VCLConfig struct {
	Name           string
	ActiveBackends int
	Status         VCLConfigStatus
}

type VCLConfigStatus 

type VCLConfigStatus int
const (
	VCLActive VCLConfigStatus = iota
	VCLAvailable
	VCLDiscarded
	VCLUnknown
)

func (VCLConfigStatus) String 

func (v VCLConfigStatus) String() string

type VCLConfigsResponse 

type VCLConfigsResponse []VCLConfig

type VCLState 

type VCLState string

VCLState describes one of the three possible VCL states See https://varnish-cache.org/docs/trunk/reference/varnish-cli.html#vcl-state-configname-auto-cold-warm 

const (
	// VCLStateAuto means that Varnish should automatically switch the VCL state
	// from "warm" to "cold" and back
	VCLStateAuto VCLState = "auto"

	// VCLStateWarm means that the VCL should always be "warm"
	VCLStateWarm VCLState = "warm"

	// VCLStateCold means that the VCL should always be "cold"
	VCLStateCold VCLState = "cold"
)

Source Files

View all Source files

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.