httpfs

Documentation

Overview

Package httpfs provides a read-only filesystem that reads from an HTTP server.

This filesystem only supports single-file operations since there is no facility in HTTP for directory listings. As such, this filesystem's behaviour does not comply with testing/fstest.TestFS.

Usage

To use this filesystem, call New with a base URL. All reads from the filesystem are relative to this base URL. Only the schemes "http" and "https" are supported.

To scope the filesystem to a specific path, use that path on the URL. For example, for a filesystem that can only read sub-paths of "https://example.com/foo/bar", you could use a URL like:

https://example.com/foo/bar/

Note: when scoping URLs to specific paths, the URL should end in "/".

Setting the Context

This filesystem supports setting a context with the fsimpl.WithContextFS extension. This can be useful in order to control timeouts, or for distributed trace propagation.

For example, to inject a context with a timeout of 3 seconds:

fsys, _ := httpfs.New(url)

ctx, cancel := context.WithTimeout(context.Background(), 3 * time.Second)
defer cancel()

fsys = fsimpl.WithContextFS(fsys, ctx)

Adding custom HTTP headers

This filesystem supports adding custom HTTP headers with the fsimpl.WithHeaderFS extension. This can be useful for setting authentication headers, or for setting a user-agent.

For example, to set the user-agent to "my-app":

fsys, _ := httpfs.New(url)

fsys = fsimpl.WithHeaderFS(fsys, http.Header{
	"User-Agent": []string{"my-app"},
})

Using your own HTTP client

By default, this filesystem uses Go's net/http.DefaultClient, but sometimes you may want to use a different HTTP client. The fsimpl.WithHTTPClientFS extension allows you to do this.

For example, to use a client with a custom transport:

fsys, _ := httpfs.New(url)

client := &http.Client{Transport: myCustomTransport}

fsys = fsimpl.WithHTTPClientFS(fsys, client)

Index

• Variables
• func New(u *url.URL) (fs.FS, error)

Examples

• New

Variables

var FS = fsimpl.FSProviderFunc(New, "http", "https")

FS is used to register this filesystem with an fsimpl.FSMux

Functions

func New

func New(u *url.URL) (fs.FS, error)

New provides a filesystem (an fs.FS) for the HTTP (or HTTPS) endpoint rooted at u. This filesystem is suitable for use with the 'http' or 'https' URL schemes. All reads are made with the GET method, while stat calls are made with the HEAD method (with a fallback to GET).

A context can be given by using WithContextFS. HTTP Headers can be provided by using WithHeaderFS.

Example

srv := setupExampleHTTPServer()
defer srv.Close()

ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
defer cancel()

base, _ := url.Parse(srv.URL)

fsys, _ := New(base)
fsys = fsimpl.WithContextFS(ctx, fsys)

b, _ := fs.ReadFile(fsys, "hello.txt")
fmt.Printf("%s", string(b))

Output:

hello, world!