Documentation
¶
Overview ¶
Package body represents the body of an HTTP request or response.
Index ¶
- type Body
- func AlreadyClosed() Body
- func Empty() Body
- func FromBytes(data []byte) Body
- func FromJSON(v interface{}) Body
- func FromPrettyJSON(v interface{}) Body
- func FromProto(msg proto.Message) Body
- func FromProtoText(msg proto.Message, o *prototext.MarshalOptions) Body
- func FromReader(r io.Reader) (Body, error)
- func FromReaderAndLength(r io.Reader, length int64) (Body, error)
- func FromString(data string) Body
- type NegativeComputedOffsetSeekError
- type NegativeStartOffsetSeekError
- type UnknownWhenceSeekError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Body ¶
type Body interface {
// BytesRemaining returns the exact number of bytes remaining in the
// Body, or -1 if the number of bytes remaining is unknown.
BytesRemaining() int64
// Read operates as per the usual io.Reader contract, filling p with as
// many bytes as it can and then returning the number of bytes filled.
// It is allowed to return short reads without error.
//
Read(p []byte) (int, error)
// Close operates as per the usual io.Closer contract, closing the Body
// and releasing as many resources as possible. As usual, the owner of
// the Body must arrange for Close() to be called when the Body is no
// longer in use.
//
// Calling Close() on the Body does not necessarily call Close() on the
// underlying Reader in a 1-to-1 fashion: Body implementations use
// reference counting during Copy(), and they use that to Close() the
// Reader only when the last copy is being closed. As such, this
// method may return nil even when the eventual call to Close() on the
// backing Reader will return non-nil.
//
// Note: even if the Body implementation in use is known to not rely on
// a backing Reader, Close() should still be called to free backing
// memory.
//
Close() error
// Copy returns a copy of this Body. The resulting copy represents the
// same bytes at the same position, but the original and the copy
// always have independent cursors.
//
// Note: this operation can be very cheap or very expensive, depending
// on the implementation.
//
// If this Body implements any advanced I/O interfaces, then so will
// the returned copy. As the two instances have independent cursors,
// calling Seek on one Body will not affect the other Body in any
// meaningful way.
//
// For Body instances which attach to a Reader, calling Close() on a
// Body will cause that Body to detach itself from the Reader using
// reference counting. If the Reader implements io.Closer, then the
// Body calls Close() on the Reader once the reference count reaches
// zero, and the resulting error (if any) is returned by the Close()
// which caused the reference counter to reach zero.
//
Copy() (Body, error)
// Unwrap will return the backing io.Reader, or nil if no such open
// Reader is currently attached to this Body.
//
// Beware that reading from the backing Reader directly or seeking its
// cursor can have unexpected visible effects, both on this Body and on
// any other copies of it.
//
Unwrap() io.Reader
}
Body represents a source of bytes, extending the io.ReadCloser interface. The intended use case is for preparing HTTP request and response bodies before sending them.
Unlike an io.ReadCloser, the length of a Body can be retrieved cheaply using the BytesRemaining() method, assuming that it is actually known.
Also unlike an io.ReadCloser, a Body can be duplicated using the Copy() method. This returns a second instance of Body that represents the same remaining bytes as this Body, but the two bodies have independent cursors and can both stream the same bytes without interfering with each other. This is true *even if* they share an underlying Reader that does not support such an operation.
Body implementations MAY also provide some of the advanced I/O interfaces defined by Go, such as io.Seeker, io.ReaderAt, or io.WriterTo.
func AlreadyClosed ¶
func AlreadyClosed() Body
AlreadyClosed returns a Body which has already been closed.
Current and future implementations make these promises:
- The returned Body implementation will provide io.ReaderAt, io.Seeker, and io.WriterTo.
func Empty ¶
func Empty() Body
Empty returns a zero-length Body which is open but already at EOF.
Current and future implementations make these promises:
- The returned Body implementation will provide io.ReaderAt, io.Seeker, and io.WriterTo.
func FromBytes ¶
FromBytes returns a new Body which serves a slice of bytes.
Note: the returned Body holds a reference to the provided slice. The slice must not be modified for the lifetime of the Body.
Current and future implementations make these promises:
- The returned Body implementation will provide io.ReaderAt, io.Seeker, and io.WriterTo.
func FromJSON ¶
func FromJSON(v interface{}) Body
FromJSON returns a new Body which serves a JSON payload.
Current and future implementations make these promises:
- The returned Body implementation will provide io.ReaderAt, io.Seeker, and io.WriterTo.
func FromPrettyJSON ¶
func FromPrettyJSON(v interface{}) Body
FromPrettyJSON returns a new Body which serves a JSON payload with indents and a terminal newline.
Current and future implementations make these promises:
- The returned Body implementation will provide io.ReaderAt, io.Seeker, and io.WriterTo.
func FromProto ¶
FromProto returns a new Body which serves a binary protobuf payload.
Current and future implementations make these promises:
- The returned Body implementation will provide io.ReaderAt, io.Seeker, and io.WriterTo.
func FromProtoText ¶
func FromProtoText(msg proto.Message, o *prototext.MarshalOptions) Body
FromProtoText returns a new Body which serves a text protobuf payload.
The MarshalOptions argument MAY be nil, in which case sensible defaults are used.
Current and future implementations make these promises:
- The returned Body implementation will provide io.ReaderAt, io.Seeker, and io.WriterTo.
func FromReader ¶
FromReader returns a new Body which serves bytes from a Reader.
If the provided Reader also implements io.Closer, then the call to Body.Close() will be forwarded to Reader.Close() if there are no other Body instances still attached to the Reader.
The provided implementation of Body may take advantage of more advanced interfaces provided by the Reader's concrete implementation, such as fs.File, io.ReaderAt, or io.Seeker.
Current and future implementations make these promises:
- If the Reader implements io.ReaderAt plus io.Seeker, or io.ReaderAt plus fs.File, then the returned implementation of Body will support io.ReaderAt and io.Seeker.
- If the Reader implements io.Seeker but not io.ReaderAt, then the returned implementation of Body will support io.Seeker and io.ReaderAt, the latter through emulation using io.ReadSeeker.
func FromReaderAndLength ¶
FromReaderAndLength returns a new Body which serves bytes from a Reader.
See FromReader for details.
func FromString ¶
FromString returns a new Body which serves bytes from a string.
Current and future implementations make these promises:
- The returned Body implementation will provide io.ReaderAt, io.Seeker, and io.WriterTo.
type NegativeComputedOffsetSeekError ¶
type NegativeComputedOffsetSeekError struct {
Offset int64
}
func (NegativeComputedOffsetSeekError) Error ¶
func (err NegativeComputedOffsetSeekError) Error() string
func (NegativeComputedOffsetSeekError) GoString ¶
func (err NegativeComputedOffsetSeekError) GoString() string
type NegativeStartOffsetSeekError ¶
type NegativeStartOffsetSeekError struct {
Offset int64
}
func (NegativeStartOffsetSeekError) Error ¶
func (err NegativeStartOffsetSeekError) Error() string
func (NegativeStartOffsetSeekError) GoString ¶
func (err NegativeStartOffsetSeekError) GoString() string
type UnknownWhenceSeekError ¶
type UnknownWhenceSeekError struct {
Whence int
}
func (UnknownWhenceSeekError) Error ¶
func (err UnknownWhenceSeekError) Error() string
func (UnknownWhenceSeekError) GoString ¶
func (err UnknownWhenceSeekError) GoString() string
Source Files