Documentation
¶
Overview ¶
Package httpclient provides a typed Go client for consuming the filer REST API.
Create a client with:
client, err := httpclient.New("http://localhost:8080/api/filer")
if err != nil {
panic(err)
}
Then use the client to manage files:
// List all backends backends, err := client.ListBackends(ctx)
Index ¶
- func MIMEByExt(ext string) string
- func SkipUnchanged(localInfo fs.FileInfo, remote *schema.Object) bool
- type Client
- func (c *Client) CreateObject(ctx context.Context, name string, req schema.CreateObjectRequest) (*schema.Object, error)
- func (c *Client) CreateObjects(ctx context.Context, name string, fsys fs.FS, opts ...UploadOpt) ([]schema.Object, error)
- func (c *Client) DeleteObject(ctx context.Context, name string, req schema.DeleteObjectRequest) (*schema.Object, error)
- func (c *Client) DeleteObjects(ctx context.Context, name string, req schema.DeleteObjectsRequest) (*schema.DeleteObjectsResponse, error)
- func (c *Client) GetObject(ctx context.Context, name string, req schema.GetObjectRequest) (*schema.Object, error)
- func (c *Client) GetObjects(ctx context.Context, name string, reqs []schema.GetObjectRequest) ([]*schema.Object, error)
- func (c *Client) ListBackends(ctx context.Context) (*schema.BackendListResponse, error)
- func (c *Client) ListObjects(ctx context.Context, name string, req schema.ListObjectsRequest) (*schema.ListObjectsResponse, error)
- func (c *Client) ReadObject(ctx context.Context, name string, req schema.ReadObjectRequest, ...) (*schema.Object, error)
- type UploadOpt
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func MIMEByExt ¶
MIMEByExt returns the MIME type for a file extension, consulting wellKnownMIME first and then the system MIME database.
func SkipUnchanged ¶ added in v0.0.5
SkipUnchanged is the default check function used by CreateObjects. It skips a file when the remote object already exists with the same size. When both the local ModTime and the remote ModTime are non-zero, they must also match (compared at second precision, since HTTP-date has no sub-second resolution).
Types ¶
type Client ¶
Client is a filer HTTP client that wraps the base HTTP client and provides typed methods for interacting with the filer API.
func New ¶
New creates a new filer HTTP client with the given base URL and options. The url parameter should point to the filer API endpoint, e.g. "http://localhost:8080/api/filer".
func (*Client) CreateObject ¶
func (c *Client) CreateObject(ctx context.Context, name string, req schema.CreateObjectRequest) (*schema.Object, error)
CreateObject uploads content using PUT, forwarding ContentType, ModTime and Meta as request headers.
func (*Client) CreateObjects ¶
func (c *Client) CreateObjects(ctx context.Context, name string, fsys fs.FS, opts ...UploadOpt) ([]schema.Object, error)
CreateObjects walks fsys and uploads every matching file to the named backend in one or more streaming multipart POSTs. To upload a subtree, pass fs.Sub(fsys, "subdir") as fsys. Options control the remote prefix, entry filter, pre-upload skip check, batch size, and progress callback; all are optional. By default files are sent in batches of 50 (WithBatchSize to override) so at most that many file handles are open at a time, bounding memory on both client and server. Files that already exist remotely with the same size (and modtime when available) are skipped. Use WithCheck(nil) to disable this.
func (*Client) DeleteObject ¶
func (c *Client) DeleteObject(ctx context.Context, name string, req schema.DeleteObjectRequest) (*schema.Object, error)
DeleteObject deletes a single object.
func (*Client) DeleteObjects ¶
func (c *Client) DeleteObjects(ctx context.Context, name string, req schema.DeleteObjectsRequest) (*schema.DeleteObjectsResponse, error)
DeleteObjects deletes objects under a path prefix (recursive or non-recursive bulk delete).
func (*Client) GetObject ¶
func (c *Client) GetObject(ctx context.Context, name string, req schema.GetObjectRequest) (*schema.Object, error)
GetObject retrieves metadata only for an object using HEAD (no body download).
func (*Client) GetObjects ¶
func (c *Client) GetObjects(ctx context.Context, name string, reqs []schema.GetObjectRequest) ([]*schema.Object, error)
GetObjects fetches metadata for multiple objects concurrently using HEAD requests, with both goroutine count and in-flight requests capped at parallelHeads via a bounded worker pool. Results are returned in the same order as reqs. Any per-request errors are joined and returned alongside partial results.
func (*Client) ListBackends ¶
ListBackends returns a list of backend URLs from the filer API.
func (*Client) ListObjects ¶
func (c *Client) ListObjects(ctx context.Context, name string, req schema.ListObjectsRequest) (*schema.ListObjectsResponse, error)
ListObjects returns a list of objects at the given backend name and optional path prefix.
func (*Client) ReadObject ¶
func (c *Client) ReadObject(ctx context.Context, name string, req schema.ReadObjectRequest, fn func([]byte) error) (*schema.Object, error)
ReadObject downloads the content of an object using GET, calling fn with each chunk of data as it arrives from the server. The slice passed to fn is reused across calls; copy it if retained. Returns the object metadata; the returned *Object is always non-nil on success.
type UploadOpt ¶
type UploadOpt func(*uploadOpts) error
UploadOpt is a functional option for CreateObjects.
func WithBatchSize ¶ added in v0.0.9
WithBatchSize sets the maximum number of files sent in each multipart POST. Smaller batches reduce peak memory on both client and server at the cost of more round-trips. The default is 50. Values above schema.MaxUploadFiles or 0 are both treated as schema.MaxUploadFiles (the server-side per-request limit).
func WithCheck ¶
WithCheck overrides the default skip check. The function receives the local fs.FileInfo and the remote schema.Object (nil when the object does not exist); return true to skip the upload for that file. Pass nil to disable skipping entirely.
func WithFilter ¶
WithFilter sets a function that controls which entries are walked. Return false to skip the entry (and its subtree when it is a directory).
func WithPrefix ¶
WithPrefix sets the remote destination prefix under which all uploaded files are stored. For example, WithPrefix("photos/2026") uploads a.txt as /photos/2026/a.txt. The default is the backend root.
func WithProgress ¶
WithProgress sets a callback that is invoked for byte-progress updates and once per committed file. index is the 0-based file position; count is the total number of files in this upload batch. written and bytes are the per-file byte counters.
Source Files