server

Documentation

Overview

Package server contains the pcopy server code. It contains a Server struct, which represents a single clipboard server, and a Router struct, which can be used to multiplex multiple clipboard servers onto the same port.

To instantiate a new clipboard Server, use New using a well-defined Config:

server := server.New(config.New())
http.ListenAndServe(":9090", http.HandlerFunc(server.Handle))

To use a Router, use NewRouter:

server1 := server.New(config1.New())
server2 := server.New(config2.New())
router := server.NewRouter(server1, server2)
router.Start()

Index

• Constants
• Variables
• func FileInfoInstructions(info *File) string
• func Serve(configs ...*config.Config) error
• type ErrHTTP
  • func (e ErrHTTP) Error() string
• type File
• type Info
• type Router
  • func NewRouter(configs ...*config.Config) (*Router, error)
  • func (r *Router) Start() error
  • func (r *Router) Stop() error
• type Server
  • func New(conf *config.Config) (*Server, error)
  • func (s *Server) Handle(w http.ResponseWriter, r *http.Request)

Constants

const (
	// HeaderStream can be sent in PUT requests to enable streaming mode (default if not set: HeaderStreamDisabled)
	HeaderStream = "X-Stream"

	// HeaderStreamDisabled is a value for the X-Stream header that can be set to disable streaming mode (the default)
	HeaderStreamDisabled = "0"

	// HeaderStreamImmediateHeaders is a value for the X-Stream header that can be set to enable streaming, and to
	// immediately send response headers before the entire request body is consumed. This is non-standard HTTP and not
	// all clients support this.
	HeaderStreamImmediateHeaders = "1"

	// HeaderStreamDelayHeaders is a value for the X-Stream header that can be set to enable streaming mode, and to
	// delay sending response headers until the request body is fully consumed. If this is used with random file ID,
	// you'll need to use reserve a file name with X-Reserve first.
	HeaderStreamDelayHeaders = "2"

	// HeaderReserve can be sent in PUT requests to enable reservation mode
	HeaderReserve = "X-Reserve"

	// HeaderReserveEnabled is a value for X-Reserve that enabled reservation mode; no other values are possible
	HeaderReserveEnabled = "1"

	// HeaderNoRedirect prevents the redirect handler from redirecting to HTTPS
	HeaderNoRedirect = "X-No-Redirect"

	// HeaderFormat can be set in PUT requests to define the response format (default if not set: HeaderFormatText)
	HeaderFormat = "X-Format"

	// HeaderFormatText is a value for X-Format that will make PUT requests return human readable instructions for
	// how to retrieve a clipboard entry
	HeaderFormatText = "text"

	// HeaderFormatJSON is a value for X-Format that will format the HTTP response for PUT requests as JSON
	HeaderFormatJSON = "json"

	// HeaderFormatNone is a value for X-Format that will not return any response body. All values will only be sent in
	// HTTP response headers.
	HeaderFormatNone = "headersonly"

	// HeaderFileMode can be set in PUT requests to define whether a file should be read-only or read-write. Allowed
	// values are config.FileModeReadWrite and config.FileModeReadOnly.
	HeaderFileMode = "X-Mode"

	// HeaderFile is a response header containing the file name / identifier for the clipboard file
	HeaderFile = "X-File"

	// HeaderTTL is a response header containing the remaining time-to-live (TTL) for the clipboard file
	HeaderTTL = "X-TTL"

	// HeaderURL is a response header containing the full URL (including auth) to access the clipboard file
	HeaderURL = "X-URL"

	// HeaderExpires is a response header containing the file expiration unix timestamp for the clipboard file
	HeaderExpires = "X-Expires"

	// HeaderCurl is a response header containing the curl command that can be used to retrieve the clipboard file
	HeaderCurl = "X-Curl"
)

Variables

var ErrHTTPBadRequest = &ErrHTTP{http.StatusBadRequest, http.StatusText(http.StatusBadRequest)}

ErrHTTPBadRequest is returned when the request sent by the client was invalid, e.g. invalid file name

var ErrHTTPMethodNotAllowed = &ErrHTTP{http.StatusMethodNotAllowed, http.StatusText(http.StatusMethodNotAllowed)}

ErrHTTPMethodNotAllowed is returned when the file state does not allow the current method, e.g. PUTting a read-only file

var ErrHTTPNotFound = &ErrHTTP{http.StatusNotFound, http.StatusText(http.StatusNotFound)}

ErrHTTPNotFound is returned when a resource is not found on the server

var ErrHTTPPartialContent = &ErrHTTP{http.StatusPartialContent, http.StatusText(http.StatusPartialContent)}

ErrHTTPPartialContent is returned when the client interrupts a stream and only partial content was sent

var ErrHTTPPayloadTooLarge = &ErrHTTP{http.StatusRequestEntityTooLarge, http.StatusText(http.StatusRequestEntityTooLarge)}

ErrHTTPPayloadTooLarge is returned when the clipboard/file-size limit has been reached

var ErrHTTPTooManyRequests = &ErrHTTP{http.StatusTooManyRequests, http.StatusText(http.StatusTooManyRequests)}

ErrHTTPTooManyRequests is returned when a server-side rate limit has been reached

var ErrHTTPUnauthorized = &ErrHTTP{http.StatusUnauthorized, http.StatusText(http.StatusUnauthorized)}

ErrHTTPUnauthorized is returned when the client has not sent proper credentials

Functions

func FileInfoInstructions

func FileInfoInstructions(info *File) string

FileInfoInstructions generates instruction text to download links

func Serve

func Serve(configs ...*config.Config) error

Serve starts a server and listens for incoming HTTPS requests. The server handles all management operations (info, verify, ...), as well as the actual clipboard functionality (GET/PUT/POST). It also starts a background process to prune old.

The function supports many configs, multiplexing based on the HTTP "Host:" header to the individual Server instances. If more than one config is passed, the "ListenAddr" configuration setting must be identical for all of them.

Types

type ErrHTTP

type ErrHTTP struct {
	Code   int
	Status string
}

ErrHTTP is a generic HTTP error for any non-200 HTTP error

func (ErrHTTP) Error

func (e ErrHTTP) Error() string

type File

type File struct {
	URL     string
	File    string
	TTL     time.Duration
	Expires time.Time
	Curl    string
}

File contains information about an uploaded file

type Info

type Info struct {
	ServerAddr string            `json:"serverAddr"`
	DefaultID  string            `json:"defaultID"`
	Salt       []byte            `json:"salt"`
	Cert       *x509.Certificate `json:"-"`
}

Info contains information about the server needed o join a server.

type Router

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

Router is a simple vhost delegator to be able to run multiple clipboards on the same port. It runs the actual HTTP(S) servers and delegates based on the configured hostname.

func NewRouter

func NewRouter(configs ...*config.Config) (*Router, error)

NewRouter creates a new multi-clipboard server using the given configs.

The function supports many configs, multiplexing based on the HTTP "Host:" header to the individual Server instances. If more than one config is passed, the "ListenAddr" configuration setting must be identical for all of them.

func (*Router) Start

func (r *Router) Start() error

Start starts the HTTP(S) server

func (*Router) Stop

func (r *Router) Stop() error

Stop immediately shuts down the HTTP(S) server. This is not a graceful shutdown.

type Server

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

Server is the main HTTP server struct. It's the one with all the good stuff.

func New

func New(conf *config.Config) (*Server, error)

New creates a new instance of a Server using the given config. It does a few sanity checks to ensure the config will likely work.

func (*Server) Handle

func (s *Server) Handle(w http.ResponseWriter, r *http.Request)

Handle is the delegating handler function for a clipboard's server. It uses the routeList to find a matching route and delegates to it.