options

package
v2.0.2 Latest Latest
Warning

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

 Go to latest Published: Jan 22, 2025 License: MIT Imports: 19 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInvalidWriterType  = errors.New("invalid writer type")
	ErrMissingFilePath    = errors.New("file path must be specified when using WriteToFile")
	ErrUnexpectedFilePath = errors.New("filepath should not be provided when using WriteToBuffer")
	ErrInvalidCompression = errors.New("unsupported compression type")
)

Common errors returned by Option methods

Functions

func ProgressWriter 

func ProgressWriter(writer io.WriteCloser, total int64, onProgress func(written, total int64)) *progressWriter

ProgressWriter creates a new progressWriter to monitor writing progress. The total parameter specifies the expected total size of the data. The onProgress callback is invoked with the current and total written values.

Types

type CompressionType 

type CompressionType string

CompressionType defines the compression algorithm used for HTTP requests. It supports standard compression types (gzip, deflate, brotli) as well as custom compression implementations. 

const (
	CompressionNone    CompressionType = ""        // No compression
	CompressionGzip    CompressionType = "gzip"    // Gzip compression (RFC 1952)
	CompressionDeflate CompressionType = "deflate" // Deflate compression (RFC 1951)
	CompressionBrotli  CompressionType = "br"      // Brotli compression
	CompressionCustom  CompressionType = "custom"  // Custom compression implementation
)

Compression types supported by the client

type Option 

type Option struct {
	Verbose                  bool                                           // Whether logging should be verbose or not
	Logger                   slog.Logger                                    // Logging - default uses the slog TextHandler
	Header                   http.Header                                    // Headers to be included in the request
	Cookies                  []*http.Cookie                                 // Cookies to be included in the request
	ProtocolScheme           string                                         // define a custom protocol scheme. It defaults to https
	Compression              CompressionType                                // CompressionType to use: none, gzip, deflate or brotli
	CustomCompressionType    CompressionType                                // When using a custom compression, specify the type to be used as the content-encoding header.
	CustomCompressor         func(w *io.PipeWriter) (io.WriteCloser, error) // Function for custom compression
	UserAgent                string                                         // User Agent to send with requests
	FollowRedirects          bool                                           // Disable or enable redirects. Default is false i.e.: follow redirects
	PreserveMethodOnRedirect bool                                           // Default is false
	MaxRedirects             int                                            // Maximum number of redirects that can happen before the client gives up

	UniqueIdentifierType UniqueIdentifierType              // Internal trace or identifier for the request
	Transport            *http.Transport                   // Create our own default transport
	ResponseWriter       ResponseWriter                    // Define the type of response writer
	UploadBufferSize     *int                              // Control the size of the buffer when uploading a file
	DownloadBufferSize   *int                              // Control the size of the buffer when downloading a file
	OnUploadProgress     func(bytesRead, totalBytes int64) // To monitor and track progress when uploading
	OnDownloadProgress   func(bytesRead, totalBytes int64) // To monitor and track progress when downloading
	// contains filtered or unexported fields
}

Option provides configuration for HTTP requests. It allows customization of various aspects of the request including headers, compression, logging, response handling, and progress tracking. If no options are provided when making a request, a default configuration is automatically generated.

func New 

func New(opts ...*Option) *Option

New creates a default Option with pre-configured settings. If additional options are provided via the variadic parameter, they will be merged with the default settings, with the provided options taking precedence.

func (*Option) AddCookie 

func (opt *Option) AddCookie(cookie *http.Cookie)

AddCookie adds a new cookie to the Option's cookie collection. If the cookie slice hasn't been initialized, it will be created.

func (*Option) AddHeader 

func (opt *Option) AddHeader(key string, value string)

AddHeader adds a new header with the specified key and value to the request headers. If the headers map hasn't been initialized, it will be created. Kept for backwards compatability

func (*Option) CheckRedirects 

func (opt *Option) CheckRedirects() bool

func (*Option) ClearCookies 

func (opt *Option) ClearCookies()

ClearCookies removes all previously set cookies from the Option.

func (*Option) ClearHeaders 

func (opt *Option) ClearHeaders()

ClearHeaders removes all previously set headers from the Option.

func (*Option) CloseFile 

func (opt *Option) CloseFile() error

CloseFile closes the currently open file if one exists and resets related metadata. It logs the closure through the configured logger and returns any error encountered during closing. After closing, the file pointer is set to nil and the filesize is reset to 0.

func (*Option) CreatePayloadReader 

func (opt *Option) CreatePayloadReader(payload any) (io.Reader, int64, error)

CreatePayloadReader converts the given payload into an io.Reader along with its size. Supported payload types include: - nil: Returns a nil reader and a size of -1. - []byte: Returns a bytes.Reader for the byte slice and its length as size. - io.Reader: Returns the reader and attempts to determine its size if it implements io.Seeker. - string: Returns a strings.Reader for the string and its length as size. For unsupported payload types, an error is returned.

func (*Option) DisableLogging 

func (opt *Option) DisableLogging()

DisableLogging turns off verbose logging for the Option instance.

func (*Option) DisablePreserveMethodOnRedirect 

func (opt *Option) DisablePreserveMethodOnRedirect()

DisablePreserveMethodOnRedirect configures redirects to not maintain the original HTTP method.

func (*Option) DisableRedirects 

func (opt *Option) DisableRedirects()

DisableRedirects configures the Option to not follow HTTP redirects.

func (*Option) EnableLogging 

func (opt *Option) EnableLogging()

EnableLogging turns on verbose logging for the Option instance.

func (*Option) EnablePreserveMethodOnRedirect 

func (opt *Option) EnablePreserveMethodOnRedirect()

EnablePreserveMethodOnRedirect configures redirects to maintain the original HTTP method.

func (*Option) EnableRedirects 

func (opt *Option) EnableRedirects()

EnableRedirects configures the Option to follow HTTP redirects.

func (*Option) Filesize 

func (opt *Option) Filesize() int64

Filesize returns the size in bytes of the currently configured file. Returns 0 if no file is set or if the file size could not be determined. This value is set when the file is initially prepared or set.

func (*Option) GenerateIdentifier 

func (opt *Option) GenerateIdentifier() string

GenerateIdentifier creates a unique identifier based on the configured UniqueIdentifierType. Returns a UUID or ULID string, or an empty string if no identifier type is configured.

func (*Option) GetClient 

func (o *Option) GetClient() *http.Client

GetClient returns the HTTP client to be used for requests. If a custom client has been set via SetClient, that client is returned. Otherwise, returns a new default http.Client instance.

func (*Option) GetCompressor 

func (opt *Option) GetCompressor(w *io.PipeWriter) (io.WriteCloser, error)

GetCompressor returns an appropriate io.WriteCloser based on the configured compression type. Returns an error if the compression type is unsupported or if a custom compressor is not properly configured.

func (*Option) GetFile 

func (opt *Option) GetFile() *os.File

GetFile returns the currently configured *os.File, if any. Returns nil if no file has been set. The returned file may be either opened or closed depending on the stage of request processing.

func (*Option) GetMaxRedirects 

func (opt *Option) GetMaxRedirects() int

func (*Option) GetWriter 

func (opt *Option) GetWriter() io.WriteCloser

GetWriter returns the currently configured io.WriteCloser instance.

func (*Option) HasFileHandle 

func (opt *Option) HasFileHandle() bool

HasFileHandle returns true if there is currently a file configured for use with this Option instance. This can be used to check if file operations should be performed during request processing.

func (*Option) InferContentType 

func (opt *Option) InferContentType(file *os.File, fileInfo os.FileInfo) error

InferContentType determines the MIME type of a file based on its content and extension. If it is unable to determine a MIME type, it defaults to application/octet-stream.

func (*Option) InitialiseWriter 

func (opt *Option) InitialiseWriter() (io.WriteCloser, error)

InitialiseWriter sets up the appropriate writer based on the ResponseWriter configuration. Returns an error if the writer type is invalid or if required parameters are missing.

func (*Option) Log 

func (opt *Option) Log(msg string, args ...any)

Log logs a message with the configured logger if verbose logging is enabled. The message will be logged at INFO level with any additional arguments provided.

func (*Option) Merge 

func (opt *Option) Merge(src *Option)

Merge combines the settings from another Option instance into this one. Settings from the source Option take precedence over existing settings. This includes headers, cookies, compression settings, and all other configuration options.

func (*Option) PrepareFile 

func (opt *Option) PrepareFile(filename string) error

PrepareFile sets up a file for upload by opening it, checking its existence, setting metadata like size and content type, and configuring appropriate headers. It takes a filename string as input and returns an error if the file cannot be accessed, doesn't exist, or fails to open. The method also automatically sets Content-Disposition headers appropriate for file uploads.

func (*Option) Redirects 

func (opt *Option) Redirects(enabled bool, preserve bool)

func (*Option) ReopenFile 

func (opt *Option) ReopenFile() (*os.File, error)

ReopenFile attempts to reopen a previously closed file using the stored filename. This is particularly useful during redirect handling when a file needs to be re-read. Returns the reopened file and any error encountered. Logs the reopening attempt through the configured logger.

func (*Option) SetBufferOutput 

func (opt *Option) SetBufferOutput()

SetBufferOutput configures the response writer to write responses to an in-memory buffer.

func (*Option) SetClient 

func (opt *Option) SetClient(client *http.Client)

SetClient configures a custom HTTP client to be used for requests. This client will be used instead of the default client for all subsequent requests made with this Option instance. The provided client should be configured with any desired settings (timeouts, transport, etc) before being set.

func (*Option) SetCompression 

func (opt *Option) SetCompression(compressionType CompressionType)

SetCompression configures the compression type to be used for the request. Valid compression types include: none, gzip, deflate, brotli, and custom.

func (*Option) SetDownloadBufferSize 

func (opt *Option) SetDownloadBufferSize(size int)

SetDownloadBufferSize configures the buffer size used when downloading files. The size must be positive; otherwise, the setting will be ignored.

func (*Option) SetFile 

func (opt *Option) SetFile(file *os.File)

SetFile configures an already-opened file for use with the client. It takes an *os.File pointer and sets internal metadata like filename and filesize. Unlike PrepareFile, this method assumes the file is already opened and valid. If file stats cannot be read, the method will silently fail rather than return an error.

func (*Option) SetFileOutput 

func (opt *Option) SetFileOutput(filepath string)

SetFileOutput configures the response writer to write responses to a file at the specified path.

func (*Option) SetLogger 

func (opt *Option) SetLogger(logger *slog.Logger)

SetLogger configures a custom logger and enables verbose logging. The provided logger will replace any existing logger configuration.

func (*Option) SetMaxRedirects 

func (opt *Option) SetMaxRedirects(size int)

func (*Option) SetOutput 

func (opt *Option) SetOutput(writerType ResponseWriterType, filepath ...string) error

SetOutput configures how the response should be written, either to a file or buffer. For file output, a filepath must be provided. Returns an error if the configuration is invalid.

func (*Option) SetProtocolScheme 

func (opt *Option) SetProtocolScheme(scheme string)

SetProtocolScheme sets the protocol scheme (e.g., "http://", "https://") for requests. If the provided scheme doesn't end with "://", it will be automatically appended.

func (*Option) SetTransport 

func (opt *Option) SetTransport(transport *http.Transport)

SetTransport configures a custom HTTP transport for the requests. This allows fine-grained control over connection pooling, timeouts, and other transport-level settings.

func (*Option) UseJsonLogger 

func (opt *Option) UseJsonLogger()

UseJsonLogger configures the Option to use a JSON-based logger and enables verbose logging. The logger will output to stdout using the default slog JSONHandler format.

func (*Option) UseTextLogger 

func (opt *Option) UseTextLogger()

UseTextLogger configures the Option to use a text-based logger and enables verbose logging. The logger will output to stdout using the default slog TextHandler format.

type ProgressReader 

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

progressReader wraps an io.Reader to track the progress of data being read. It reports progress using the onProgress callback, which is invoked with the number of bytes read so far and the total bytes expected to be read.

func NewProgressReader 

func NewProgressReader(reader io.Reader, total int64, onProgress func(read, total int64)) *ProgressReader

ProgressReader creates a new progressReader to monitor reading progress. The total parameter specifies the expected total size of the data. The onProgress callback is invoked with the current and total read values.

func (*ProgressReader) CloneForRedirect 

func (pr *ProgressReader) CloneForRedirect() *ProgressReader

CloneForRedirect creates a new progressReader that shares progress tracking with the original reader, making it safe for redirect chains

func (*ProgressReader) GetProgress 

func (pr *ProgressReader) GetProgress() int64

GetProgress returns the current number of bytes read

func (*ProgressReader) Read 

func (pr *ProgressReader) Read(p []byte) (int, error)

Read reads data from the underlying io.Reader and tracks the number of bytes read.

type ResponseWriter 

type ResponseWriter struct {
	// Type determines the destination for response data.
	// Must be either WriteToBuffer or WriteToFile.
	Type ResponseWriterType

	// FilePath specifies the destination file path when Type is WriteToFile.
	// This field is ignored when Type is WriteToBuffer.
	// The path must be writable and will be created if it doesn't exist.
	FilePath string
	// contains filtered or unexported fields
}

ResponseWriter contains configuration for handling HTTP response bodies. It supports writing responses either to an in-memory buffer or directly to a file, allowing for flexible response handling based on the needs of the caller.

type ResponseWriterType 

type ResponseWriterType string

ResponseWriterType defines how the HTTP response body should be handled. It determines whether responses are written to an in-memory buffer or directly to a file. 

const (
	// WriteToBuffer indicates that responses should be written to an in-memory buffer.
	// This is useful for smaller responses that need to be processed in memory.
	WriteToBuffer ResponseWriterType = "buffer"

	// WriteToFile indicates that responses should be written directly to a file.
	// This is recommended for large responses to minimize memory usage.
	WriteToFile ResponseWriterType = "file"
)

Supported response writer types

type UniqueIdentifierType 

type UniqueIdentifierType string

UniqueIdentifierType defines the type of unique identifier to use for request tracing. It supports both UUID and ULID formats. 

const (
	IdentifierNone UniqueIdentifierType = ""     // No identifier
	IdentifierUUID UniqueIdentifierType = "uuid" // UUID v4
	IdentifierULID UniqueIdentifierType = "ulid" // ULID timestamp-based identifier
)

Supported identifier types for request tracing

type WriteCloserBuffer 

type WriteCloserBuffer struct {
	*bytes.Buffer
}

WriteCloserBuffer is a wrapper around bytes.Buffer that implements the io.WriteCloser interface. It is used as an in-memory buffer for writing data where closing the buffer does not require any additional cleanup or resource management.

func (*WriteCloserBuffer) Close 

func (wcb *WriteCloserBuffer) Close() error

Close satisfies the io.WriteCloser interface but performs no action. This is because there are no resources to release or clean up for an in-memory buffer.

func (*WriteCloserBuffer) IsEmpty 

func (w *WriteCloserBuffer) IsEmpty() bool

Determine if the bytes.Buffer is empty

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.