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 ¶
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" )
const (
// DefaultMethod is the default HTTP method used when none is supplied
DefaultMethod = "GET"
)
Variables ¶
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.
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.
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 ¶
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 ¶
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 ¶
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
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.
Source Files