servecontent

Documentation

Index

• Variables
• func DetectContentType(ctx context.Context, name string, f RangeFunc) (string, error)
• func ETagStrongMatch(a, b string) bool
• func ETagWeakMatch(a, b string) bool
• func EvaluatePreconditions(w http.ResponseWriter, r *http.Request, modtime time.Time, etag string) (done bool)
• func RangesMIMESize(ranges []HTTPRange, contentType string, contentSize int64) (encSize int64)
• func ScanETag(s string) (etag string, remain string)
• func ServeContent(ctx context.Context, w http.ResponseWriter, r *http.Request, content Content)
• func ServeReadSeeker(ctx context.Context, w http.ResponseWriter, r *http.Request, name string, ...)
• func SumRangesSize(ranges []HTTPRange) (size int64)
• func WriteNotModified(w http.ResponseWriter)
• type CondResult
  • func CheckIfMatch(h http.Header, etag string) CondResult
  • func CheckIfModifiedSince(r *http.Request, modtime time.Time) CondResult
  • func CheckIfNoneMatch(h http.Header, etag string) CondResult
  • func CheckIfRange(r *http.Request, etag string, modtime time.Time) CondResult
  • func CheckIfUnmodifiedSince(h http.Header, modtime time.Time) CondResult
• type Content
• type HTTPRange
  • func ParseRange(s string, size int64) ([]HTTPRange, error)
  • func (r HTTPRange) ContentRange(size int64) string
  • func (r HTTPRange) MIMEHeader(contentType string, size int64) textproto.MIMEHeader
• type RangeFunc

Variables

var (
	ErrInvalidOffset = errors.New("invalid offset")
)

var ErrNoOverlap = errors.New("invalid range: failed to overlap")

ErrNoOverlap is returned by ParseRange if first-byte-pos of all of the byte-range-spec values is greater than the content size.

Functions

func DetectContentType

func DetectContentType(ctx context.Context, name string, f RangeFunc) (string, error)

func ETagStrongMatch

func ETagStrongMatch(a, b string) bool

ETagStrongMatch reports whether a and b match using strong ETag comparison. Assumes a and b are valid ETags.

func ETagWeakMatch

func ETagWeakMatch(a, b string) bool

ETagWeakMatch reports whether a and b match using weak ETag comparison. Assumes a and b are valid ETags.

func EvaluatePreconditions

func EvaluatePreconditions(w http.ResponseWriter, r *http.Request, modtime time.Time, etag string) (done bool)

EvaluatePreconditions evaluates request preconditions and reports whether a precondition resulted in sending StatusNotModified or StatusPreconditionFailed.

func RangesMIMESize

func RangesMIMESize(ranges []HTTPRange, contentType string, contentSize int64) (encSize int64)

RangesMIMESize returns the number of bytes it takes to encode the provided ranges as a multipart response.

func ScanETag

func ScanETag(s string) (etag string, remain string)

ScanETag determines if a syntactically valid ETag is present at s. If so, the ETag and remaining text after consuming ETag is returned. Otherwise, it returns "", "".

func ServeContent

func ServeContent(ctx context.Context, w http.ResponseWriter, r *http.Request, content Content)

TODO: update documentation here ServeContent replies to the request using the content in the provided ReadSeeker. The main benefit of ServeContent over io.Copy is that it handles Range requests properly, sets the MIME type, and handles If-Match, If-Unmodified-Since, If-None-Match, If-Modified-Since, and If-Range requests.

If the response's Content-Type header is not set, ServeContent first tries to deduce the type from name's file extension and, if that fails, falls back to reading the first block of the content and passing it to DetectContentType. The name is otherwise unused; in particular it can be empty and is never sent in the response.

If modtime is not the zero time or Unix epoch, ServeContent includes it in a Last-Modified header in the response. If the request includes an If-Modified-Since header, ServeContent uses modtime to decide whether the content needs to be sent at all.

The content's Seek method must work: ServeContent uses a seek to the end of the content to determine its size.

If the caller has set w's ETag header formatted per RFC 7232, section 2.3, ServeContent uses it to handle requests using If-Match, If-None-Match, or If-Range.

Note that *os.File implements the io.ReadSeeker interface.

func ServeReadSeeker

func ServeReadSeeker(ctx context.Context, w http.ResponseWriter, r *http.Request, name string, modtime time.Time, fh io.ReadSeeker)

func SumRangesSize

func SumRangesSize(ranges []HTTPRange) (size int64)

func WriteNotModified

func WriteNotModified(w http.ResponseWriter)

Types

type CondResult

type CondResult int

CondResult is the result of an HTTP request precondition check. See https://tools.ietf.org/html/rfc7232 section 3.

const (
	CondNone CondResult = iota
	CondTrue
	CondFalse
)

func CheckIfMatch

func CheckIfMatch(h http.Header, etag string) CondResult

func CheckIfModifiedSince

func CheckIfModifiedSince(r *http.Request, modtime time.Time) CondResult

func CheckIfNoneMatch

func CheckIfNoneMatch(h http.Header, etag string) CondResult

func CheckIfRange

func CheckIfRange(r *http.Request, etag string, modtime time.Time) CondResult

func CheckIfUnmodifiedSince

func CheckIfUnmodifiedSince(h http.Header, modtime time.Time) CondResult

type Content

type Content struct {
	ContentType func(ctx context.Context) (string, error)
	ETag        string
	ModTime     time.Time
	Size        func(ctx context.Context) (size int64, err error)
	Range       RangeFunc
}

type HTTPRange

type HTTPRange struct {
	Start, Length int64
}

HTTPRange specifies the byte range to be sent to the client.

func ParseRange

func ParseRange(s string, size int64) ([]HTTPRange, error)

ParseRange parses a Range header string as per RFC 7233. ErrNoOverlap is returned if none of the ranges overlap.

func (HTTPRange) ContentRange

func (r HTTPRange) ContentRange(size int64) string

func (HTTPRange) MIMEHeader

func (r HTTPRange) MIMEHeader(contentType string, size int64) textproto.MIMEHeader

type RangeFunc

type RangeFunc func(ctx context.Context, offset, length int64) (io.ReadCloser, error)

RangeFunc represents a way of getting a range of data from a stream. If length == -1, the range from the offset to the end is requested. offset and length are *not* guaranteed to be within the stream's size. If the offset is not a valid offset, the RangeFunc should return an error where errors.Is(err, ErrInvalidOffset) is true. If the length runs off the end of the object, errors.Is(err, io.EOF) is expected whenever the stream actually ends. io.ErrUnexpectedEOF is reserved for other conditions.