resource

package
v1.3.2 Latest Latest
Warning

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

Go to latest
Published: Sep 5, 2019 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package resource provides common resource-handling functionality.

This package is heavily inspired by frameworks like Spring. The concept is that external resources, such as files or HTTP content, can be configured via JSON and then consumed via a common interface.

Index

Constants

View Source
const (
	// NoScheme indicates the value of a URI without a scheme prefix, e.g. "/etc/appname/config.json"
	NoScheme = ""

	// FileScheme indicates a file URI according to https://en.wikipedia.org/wiki/File_URI_scheme.
	// When a URL is parsed that has no scheme, url.URL.Scheme is set to this value.
	FileScheme = "file"

	// HttpScheme is plain old HTTP
	HttpScheme = "http"

	// HttpsScheme is secure HTTP
	HttpsScheme = "https"
)
View Source
const (
	// DefaultMethod is the default HTTP method used when none is supplied
	DefaultMethod = "GET"
)

Variables

View Source
var (
	ErrorAmbiguousResource = errors.New("Either URI or Data must be supplied, but not both")
	ErrorNoResource        = errors.New("URI or Data are required")
	ErrorURIRequired       = errors.New("A URI is required")
)

Functions

func MustParse

func MustParse(uriTemplate string) *uritemplates.UriTemplate

MustParse parses the given URI template and panics if there is an error. Useful for initializing global variables or struct literals.

func ReadAll

func ReadAll(loader Loader) ([]byte, error)

ReadAll is an analog to ioutil.ReadAll: it reads the entire resource into a single byte slice, returning any error that occurred.

func UseClient

func UseClient(loader Loader, HTTPClient httpClient)

UseClient will change the HTTP client object used by the given resource. If loader is not an HTTP Loader, this function does nothing. A nil client will cause the loader to use http.DefaultClient.

Types

type Data

type Data struct {
	Source []byte
}

Data is an in-memory resource. It is a Loader which simple reads from a byte slice.

func (*Data) Location

func (loader *Data) Location() string

func (*Data) Open

func (loader *Data) Open() (io.ReadCloser, error)

func (*Data) String

func (loader *Data) String() string

type Expander

type Expander interface {
	// Names returns a slice containing the parameter names in the URI template.
	// This can be the empty slice for templates which do not contain any parameters.
	// Templates without parameters will simply return Loader instances from Expand
	// that refer to the same location.
	Names() []string

	// Expand uses the supplied object as a source for name/value pairs to use
	// when expanding the URI template.  Typically, this method is called with
	// a map[string]interface{} or a struct whose exported members supply the name/value
	// pairs.
	//
	// Names which are not present in the internal URI template are ignored.  Also,
	// template parameters which are not supplied in the values are emitted as is, e.g. "{name}",
	// in the internal URI used by the Loader.
	Expand(interface{}) (Loader, error)
}

Expander is a strategy for expanding URI templates into resource Loaders.

type Factory

type Factory struct {
	// URI specifies the external resource's location.  This can be a filesystem
	// path, which is a valid URI.  file:// resources are also supported.
	URI string `json:"uri"`

	// Data specfies the actual data of the resource.  Either this or URI
	// must be set, but not both.
	Data string `json:"data"`

	// Header supplies any HTTP headers to use when obtaining the resource.
	// Ignored if URI is not an HTTP or HTTPS URI.
	Header http.Header `json:"header"`

	// Method is the HTTP method to use when obtaining the resource.
	// Ignored if URI is not an HTTP or HTTPS URI.
	Method string `json:"method"`

	// HTTPClient is any object that supplies a method with the signature func(*http.Request) (*http.Response, error).
	// It is omitted from all JSON operations, so it must be supplied after a Factory is unmarshalled.
	// If not supplied, http.DefaultClient is used.  Any *http.Client value can be used here so that
	// all resources share a common Client configuration.
	//
	// Ignored if URI is not an HTTP or HTTPS URI.
	HTTPClient httpClient `json:"-"`
}

Factory provides a common way to configure all types of resources supported by this package. This type allows client code to use JSON configuration to specify resources in an abstract way.

The primary purpose for this type is to allow external configuration of application resources in a file or other source of JSON. For code which does not require this level of abstraction, the other resources types in this package (e.g. HTTP, Data, Template, etc) can be used directly.

func (*Factory) NewExpander

func (f *Factory) NewExpander(requiredNames ...string) (Expander, error)

NewExpander treats URI as a URI template and produces an Expander object which can be used to expand the URI template into Loader instances.

If any requiredNames are supplied, an error will be returned if the URI template does not contain only those names.

func (*Factory) NewLoader

func (f *Factory) NewLoader() (Loader, error)

NewLoader creates a Loader which loads from the literal URI. The URI must be a valid URL with the file, http, or https schemes.

func (*Factory) URL

func (f *Factory) URL() (*url.URL, error)

URL returns the url.URL that should be used to obtain the resource. If this factory represents an in-memory resource, a nil url.URL pointer is returned.

This method also does basic validation on the state of the factory. If the returned error is non-nil, the url will always be nil.

type File

type File struct {
	Path string
}

File is a Loader which obtains resources from the filesystem

func (*File) Location

func (loader *File) Location() string

func (*File) Open

func (loader *File) Open() (reader io.ReadCloser, err error)

func (*File) String

func (loader *File) String() string

type HTTP

type HTTP struct {
	URL        string
	Header     http.Header
	Method     string
	HTTPClient httpClient
}

HTTP is a Loader which obtains resources via HTTP.

func (*HTTP) Location

func (loader *HTTP) Location() string

func (*HTTP) Open

func (loader *HTTP) Open() (reader io.ReadCloser, err error)

func (*HTTP) String

func (loader *HTTP) String() string

type Loader

type Loader interface {
	// Location returns a string identifying where this Loader
	// gets its data from
	Location() string

	// Open returns a ReadCloser that reads this resource's data.
	Open() (io.ReadCloser, error)
}

Loader represents a type that can load data, potentially from outside the running process.

type Template

type Template struct {
	URITemplate *uritemplates.UriTemplate
	Header      http.Header
	Method      string
	HTTPClient  httpClient
}

Template is an Expander implementation which uses a uritemplates.UriTemplate to generate URIs. The URIs are then supplied to a Factory which is used to produce the Loaders.

Typically, a Factory will be used to create instances of this type, which are used through the Expander interface. However, this type is exported for simple use cases which do not require the full configuration logic of a Factory.

func (*Template) Expand

func (t *Template) Expand(value interface{}) (Loader, error)

func (*Template) Names

func (t *Template) Names() []string

func (*Template) String

func (t *Template) String() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL