txtdirect

README

Convenient redirects based on DNS TXT-records

NOTE: This is a beta release, we do not consider it completely production ready yet. Use at your own risk.

TXTDirect

Convenient and minimalistic DNS based redirects, while controlling your data with your own DNS records.

Using TXTDirect

Take a look at our full documentation.

Support

For detailed information on support options see our support guide.

Helping out

Best place to start is our contribution guide.

---

Code is licensed under the Apache License, Version 2.0.
Documentation/examples are licensed under Creative Commons BY-SA 4.0.
Illustrations, trademarks and third-party resources are owned by their respective party and are subject to different licensing.

The TXTDIRECT logo was created by Florin Luca

---

Copyright 2017 - The TXTDirect Authors

Documentation

Index

• Variables
• func ParseRecord(str string, w http.ResponseWriter, req *http.Request, c Config) (record, error)
• func ParseURI(uri string, w http.ResponseWriter, r *http.Request, c Config) string
• func Redirect(w http.ResponseWriter, r *http.Request, c Config) error
• func UpstreamZone(r *http.Request) string
• type Config
  • func ParseConfig(c *caddy.Controller) (Config, error)
• type Dockerv2
  • func NewDockerv2(w http.ResponseWriter, r *http.Request, rec record, c Config) *Dockerv2
  • func (d *Dockerv2) ParseRecordReference() error
  • func (d *Dockerv2) ParseReference() (string, error)
  • func (d *Dockerv2) Redirect() error
• type Fallback
• type Git
  • func NewGit(w http.ResponseWriter, r *http.Request, c Config, rec record) *Git
  • func (g *Git) Proxy() error
  • func (g *Git) ValidGitQuery() bool
• type Gometa
  • func NewGometa(w http.ResponseWriter, r *http.Request, rec record, c Config) *Gometa
  • func (g *Gometa) Serve() error
  • func (g *Gometa) ValidQuery() bool
• type Host
  • func NewHost(w http.ResponseWriter, r *http.Request, rec record, c Config) *Host
  • func (h *Host) Redirect() error
• type Image
• type Path
  • func NewPath(w http.ResponseWriter, r *http.Request, path string, rec record, c Config) *Path
  • func (p *Path) Redirect() *record
  • func (p *Path) RedirectRoot() error
  • func (p *Path) SpecificRecord() (*record, error)
• type Prometheus
  • func (p *Prometheus) ParsePrometheus(c *caddy.Controller, key, value string) error
  • func (p *Prometheus) ServeHTTP(w http.ResponseWriter, r *http.Request) (int, error)
  • func (p *Prometheus) SetDefaults()
  • func (p *Prometheus) Setup(c *caddy.Controller)
• type Proxy
  • func NewProxy(w http.ResponseWriter, r *http.Request, rec record, c Config) *Proxy
  • func (p *Proxy) Proxy() error
• type ProxyResponse
  • func (p *ProxyResponse) Body() []byte
  • func (p *ProxyResponse) Header() http.Header
  • func (p *ProxyResponse) ReplaceBody(scheme, to, host string) error
  • func (p *ProxyResponse) Write(body []byte) (int, error)
  • func (p *ProxyResponse) WriteBody() error
  • func (p *ProxyResponse) WriteHeader(status int)
• type Qr
  • func (qr *Qr) ParseColors() error
  • func (qr *Qr) ParseQr(c *caddy.Controller) error
  • func (qr *Qr) Redirect(w http.ResponseWriter, r *http.Request) error
  • func (qr *Qr) SetDefaults()
• type RegexRecord
• type TXTDirect
  • func (rd TXTDirect) ServeHTTP(w http.ResponseWriter, r *http.Request) (int, error)

Variables

var (
	// RequestsCount counts the total requests per host
	RequestsCount = prometheus.NewCounterVec(prometheus.CounterOpts{
		Namespace: "txtdirect",
		Name:      "redirect_count_total",
		Help:      "Total requests per host",
	}, []string{"host"})

	// RequestsByStatus counts the total returned statuses per host
	RequestsByStatus = prometheus.NewCounterVec(prometheus.CounterOpts{
		Namespace: "txtdirect",
		Name:      "redirect_status_count_total",
		Help:      "Total returned statuses per host",
	}, []string{"host", "status"})

	// RequestsCountBasedOnType counts the total requests for each host based on type
	RequestsCountBasedOnType = prometheus.NewCounterVec(prometheus.CounterOpts{
		Namespace: "txtdirect",
		Name:      "redirect_type_count_total",
		Help:      "Total requests for each host based on type",
	}, []string{"host", "type"})

	// FallbacksCount counts the total fallbacks triggered for each type
	FallbacksCount = prometheus.NewCounterVec(prometheus.CounterOpts{
		Namespace: "txtdirect",
		Name:      "fallback_type_count_total",
		Help:      "Total fallbacks triggered for each type",
	}, []string{"host", "type", "fallback"})

	// PathRedirectCount counts the total redirects per path for each host
	PathRedirectCount = prometheus.NewCounterVec(prometheus.CounterOpts{
		Namespace: "txtdirect",
		Name:      "redirect_path_count_total",
		Help:      "Total redirects per path for each host",
	}, []string{"host", "path"})
)

var FromRegex = regexp.MustCompile("\\/\\$(\\d+)")

FromRegex parses the from= field

var GroupOrderRegex = regexp.MustCompile("P<([a-zA-Z]+[a-zA-Z0-9]*)>")

GroupOrderRegex finds the order of regex groups inside re=

var GroupRegex = regexp.MustCompile("P<[a-zA-Z]+[a-zA-Z0-9]*>")

GroupRegex parses the re= field to find the regex groups

var PathRegex = regexp.MustCompile("\\/([A-Za-z0-9-._~!$'()*+,;=:@]+)")

PathRegex is the default regex to parse request's path It can be replaced using the re= field in the records

var PlaceholderRegex = regexp.MustCompile("{[~>?]?\\w+}")

PlaceholderRegex finds the placeholders like {x}

Functions

func ParseRecord

func ParseRecord(str string, w http.ResponseWriter, req *http.Request, c Config) (record, error)

ParseRecord takes a string containing the DNS TXT record and returns a TXTDirect record struct instance. It will return an error if the DNS TXT record is not standard or if the record type is not enabled in the TXTDirect's config.

func ParseURI

func ParseURI(uri string, w http.ResponseWriter, r *http.Request, c Config) string

ParseURI parses the given URI and triggers fallback if the URI isn't valid

func Redirect

func Redirect(w http.ResponseWriter, r *http.Request, c Config) error

Redirect the request depending on the redirect record found

func UpstreamZone

func UpstreamZone(r *http.Request) string

Types

type Config

type Config struct {
	Enable     []string
	Redirect   string
	Resolver   string
	LogOutput  string
	Prometheus Prometheus
	Qr         Qr
}

Config contains the middleware's configuration

func ParseConfig

func ParseConfig(c *caddy.Controller) (Config, error)

type Dockerv2

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

Dockerv2 keeps data for "dockerv2" type requests

func NewDockerv2

func NewDockerv2(w http.ResponseWriter, r *http.Request, rec record, c Config) *Dockerv2

NewDockerv2 returns a fresh instance of Dockerv2 struct

func (*Dockerv2) ParseRecordReference

func (d *Dockerv2) ParseRecordReference() error

func (*Dockerv2) ParseReference

func (d *Dockerv2) ParseReference() (string, error)

func (*Dockerv2) Redirect

func (d *Dockerv2) Redirect() error

Redirect handles the requests for "dockerv2" type

type Fallback

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

Fallback keeps the data necessary for the fallback flow

type Git

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

Git keeps data for "git" type requests

func NewGit

func NewGit(w http.ResponseWriter, r *http.Request, c Config, rec record) *Git

NewGit returns a fresh instance of Git struct

func (*Git) Proxy

func (g *Git) Proxy() error

Proxy handles the requests for "git" type

func (*Git) ValidGitQuery

func (g *Git) ValidGitQuery() bool

ValidGitQuery checks the User-Agent header to make sure the requests are coming from a Git client.

type Gometa

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

Gometa keeps data for "gometa" type requests

func NewGometa

func NewGometa(w http.ResponseWriter, r *http.Request, rec record, c Config) *Gometa

NewGometa returns a fresh instance of Gometa struct

func (*Gometa) Serve

func (g *Gometa) Serve() error

Serve executes a template on the given ResponseWriter that contains go-import meta tag

func (*Gometa) ValidQuery

func (g *Gometa) ValidQuery() bool

ValidQuery checks the request query to make sure the requests are coming from the Go tool.

type Host

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

Host keeps data for "host" type requests

func NewHost

func NewHost(w http.ResponseWriter, r *http.Request, rec record, c Config) *Host

NewHost returns a fresh instance of Host struct

func (*Host) Redirect

func (h *Host) Redirect() error

Redirect redirects the request to the endpoint defined in the record

type Image

type Image struct {
	Registry string
	Image    string
	Tag      string
}

type Path

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

Path contains the data that are needed to redirect path requests

func NewPath

func NewPath(w http.ResponseWriter, r *http.Request, path string, rec record, c Config) *Path

NewPath returns an instance of Path struct using the given data

func (*Path) Redirect

func (p *Path) Redirect() *record

Redirect finds and returns the final record

func (*Path) RedirectRoot

func (p *Path) RedirectRoot() error

RedirectRoot redirects the request to record's root= field if the path is empty or "/". If the root= field is empty too fallback will be triggered.

func (*Path) SpecificRecord

func (p *Path) SpecificRecord() (*record, error)

SpecificRecord finds the most specific match using the custom regexes from subzones It goes through all the custom regexes specified in each subzone and uses the most specific match to return the final record.

type Prometheus

type Prometheus struct {
	Enable        bool
	Address       string
	Path          string
	PathWhitelist []string
	// contains filtered or unexported fields
}

Prometheus contains Prometheus's configuration

func (*Prometheus) ParsePrometheus

func (p *Prometheus) ParsePrometheus(c *caddy.Controller, key, value string) error

ParsePrometheus parses the txtdirect config for Prometheus

func (*Prometheus) ServeHTTP

func (p *Prometheus) ServeHTTP(w http.ResponseWriter, r *http.Request) (int, error)

func (*Prometheus) SetDefaults

func (p *Prometheus) SetDefaults()

SetDefaults sets the default values for prometheus config if the fields are empty

func (*Prometheus) Setup

func (p *Prometheus) Setup(c *caddy.Controller)

Setup registers the metrics on startup and creates the promethues request handler

type Proxy

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

Proxy contains the data that are needed to proxy the request

func NewProxy

func NewProxy(w http.ResponseWriter, r *http.Request, rec record, c Config) *Proxy

NewProxy returns a fresh instance of Proxy struct

func (*Proxy) Proxy

func (p *Proxy) Proxy() error

Proxy proxies the request to the endpoint defined in the record

type ProxyResponse

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

ProxyResponse keeps the custom response writer data and is a custom implementation of net/http's default response writer

func (*ProxyResponse) Body

func (p *ProxyResponse) Body() []byte

Body returns response's body. This method should only get called after WriteBody()

func (*ProxyResponse) Header

func (p *ProxyResponse) Header() http.Header

Header returns response headers

func (*ProxyResponse) ReplaceBody

func (p *ProxyResponse) ReplaceBody(scheme, to, host string) error

ReplaceBody replaces the URIs inside the response body to use the request's host instead of the endpoint's host

func (*ProxyResponse) Write

func (p *ProxyResponse) Write(body []byte) (int, error)

func (*ProxyResponse) WriteBody

func (p *ProxyResponse) WriteBody() error

WriteBody writes the response body to custom response writer's body

func (*ProxyResponse) WriteHeader

func (p *ProxyResponse) WriteHeader(status int)

WriteHeader Writes the given status code to response

type Qr

type Qr struct {
	Enable          bool
	Size            int
	BackgroundColor string
	ForegroundColor string
	RecoveryLevel   qrcode.RecoveryLevel
	// contains filtered or unexported fields
}

Qr contains Qr code generator's configuration

func (*Qr) ParseColors

func (qr *Qr) ParseColors() error

ParseColors parses the hex colors in the QR config to color.Color instances

func (*Qr) ParseQr

func (qr *Qr) ParseQr(c *caddy.Controller) error

ParseQr parses the config for QR requests

func (*Qr) Redirect

func (qr *Qr) Redirect(w http.ResponseWriter, r *http.Request) error

Redirect handles the requests for "qr" requests

func (*Qr) SetDefaults

func (qr *Qr) SetDefaults()

SetDefaults sets the default values for QR config

type RegexRecord

type RegexRecord struct {
	Position   int
	TXT        string
	Regex      string
	Submatches []string
}

RegexRecord holds the TXT record and re= field of a predefined regex record

type TXTDirect

type TXTDirect struct {
	Next   httpserver.Handler
	Config Config
}

TXTDirect is middleware to redirect requests based on TXT records

func (TXTDirect) ServeHTTP

func (rd TXTDirect) ServeHTTP(w http.ResponseWriter, r *http.Request) (int, error)