w3s

README

go-w3s-client

A client to the Web3.Storage API.

Demo: https://youtu.be/FLsQZ_ogeOg

Install

go get github.com/web3-storage/go-w3s-client

Usage

package main

import (
    "io/fs"
    "os"
    "github.com/web3-storage/go-w3s-client"
)

func main() {
    c, _ := w3s.NewClient(w3s.WithToken("<AUTH_TOKEN>"))
    f, _ := os.Open("images/pinpie.jpg")

    // OR add a whole directory:
    //
    //   f, _ := os.Open("images")
    //
    // OR create your own directory:
    //
    //   img0, _ := os.Open("aliens.jpg")
    //   img1, _ := os.Open("donotresist.jpg")
    //   f := w3fs.NewDir("images", []fs.File{img0, img1})

    // Write a file/directory
    cid, _ := c.Put(context.Background(), f)
    fmt.Printf("https://%v.ipfs.dweb.link\n", cid)

    // Retrieve a file/directory
    res, _ := c.Get(context.Background(), cid)
    
    // res is a http.Response with an extra method for reading IPFS UnixFS files!
    f, fsys, _ := res.Files()

    // List directory entries
    if d, ok := f.(fs.ReadDirFile); ok {
        ents, _ := d.ReadDir(0)
        for _, ent := range ents {
            fmt.Println(ent.Name())
        }
    }

    // Walk whole directory contents (including nested directories)
    fs.WalkDir(fsys, "/", func(path string, d fs.DirEntry, err error) error {
        info, _ := d.Info()
        fmt.Printf("%s (%d bytes)\n", path, info.Size())
        return err
    })

    // Open a file in a directory
    img, _ := fsys.Open("pinpie.jpg")
    // img.Stat()
    // img.Read(...)
    // img.Close()
}

See example for more.

API

pkg.go.dev Reference

Contribute

Feel free to dive in! Open an issue or submit PRs.

License

Dual-licensed under MIT + Apache 2.0

Documentation

Index

• Constants
• type Client
  • func NewClient(options ...Option) (Client, error)
• type Deal
  • func (d *Deal) UnmarshalJSON(b []byte) error
• type DealStatus
  • func (s DealStatus) String() string
• type ListOption
  • func WithBefore(before time.Time) ListOption
  • func WithMaxResults(maxResults int) ListOption
• type Option
  • func WithDatastore(ds ds.Batching) Option
  • func WithEndpoint(endpoint string) Option
  • func WithHTTPClient(hc *http.Client) Option
  • func WithToken(token string) Option
• type Pin
  • func (p *Pin) UnmarshalJSON(b []byte) error
• type PinOption
  • func WithPinMeta(key, value string) PinOption
  • func WithPinName(name string) PinOption
  • func WithPinOrigin(ma string) PinOption
• type PinResponse
  • func (p *PinResponse) UnmarshalJSON(b []byte) error
• type PinResponseDetail
  • func (p *PinResponseDetail) UnmarshalJSON(b []byte) error
• type PinStatus
  • func (s PinStatus) String() string
• type PutOption
  • func WithDirname(dirname string) PutOption
  • func WithFs(fsys fs.FS) PutOption
• type Status
  • func (s *Status) UnmarshalJSON(b []byte) error
• type UploadIterator
  • func (li *UploadIterator) Next() (*Status, error)

Constants

const (
	PinStatusPinned    = PinStatus(api.TrackerStatusPinned)
	PinStatusPinning   = PinStatus(api.TrackerStatusPinning)
	PinStatusPinQueued = PinStatus(api.TrackerStatusPinQueued)
	PinStatusRemote    = PinStatus(api.TrackerStatusRemote)
	PinStatusUnpinned  = PinStatus(api.TrackerStatusUnpinned)
	PinStatusUnknown   = PinStatus(-1)
)

Types

type Client

type Client interface {
	Get(context.Context, cid.Cid) (*w3http.Web3Response, error)
	Put(context.Context, fs.File, ...PutOption) (cid.Cid, error)
	PutCar(context.Context, io.Reader) (cid.Cid, error)
	Status(context.Context, cid.Cid) (*Status, error)
	List(context.Context, ...ListOption) (*UploadIterator, error)
	Pin(context.Context, cid.Cid, ...PinOption) (*PinResponse, error)
}

Client is a HTTP API client to the web3.storage service.

func NewClient

func NewClient(options ...Option) (Client, error)

NewClient creates a new web3.storage API client.

type Deal

type Deal struct {
	DealID            uint64
	StorageProvider   address.Address
	Status            DealStatus
	PieceCid          cid.Cid
	DataCid           cid.Cid
	DataModelSelector string
	Activation        time.Time
	Created           time.Time
	Updated           time.Time
}

func (*Deal) UnmarshalJSON

func (d *Deal) UnmarshalJSON(b []byte) error

type DealStatus

type DealStatus int

const (
	DealStatusQueued DealStatus = iota
	DealStatusPublished
	DealStatusActive
)

func (DealStatus) String

func (s DealStatus) String() string

type ListOption

type ListOption func(cfg *listConfig) error

ListOption is an option configuring a call to List.

func WithBefore

func WithBefore(before time.Time) ListOption

WithBefore sets the time that items in the list were uploaded before.

func WithMaxResults

func WithMaxResults(maxResults int) ListOption

WithMaxResults sets the maximum number of results that will be available from the iterator.

type Option

type Option func(cfg *clientConfig) error

Option is an option configuring a web3.storage client.

func WithDatastore

func WithDatastore(ds ds.Batching) Option

WithDatastore sets the underlying datastore to use when reading or writing DAG block data. The default is to use a new in-memory store per Get/Put request.

func WithEndpoint

func WithEndpoint(endpoint string) Option

WithEndpoint sets the URL of the root API when making requests (default https://api.web3.storage).

func WithHTTPClient

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient sets the HTTP client to use when making requests which allows timeouts and redirect behaviour to be configured. The default is to use the DefaultClient from the Go standard library.

func WithToken

func WithToken(token string) Option

WithToken sets the auth token to use in the Authorization header when making requests to the API.

type Pin

type Pin struct {
	PeerID   peer.ID
	PeerName string
	Region   string
	Status   PinStatus
	Updated  time.Time
}

func (*Pin) UnmarshalJSON

func (p *Pin) UnmarshalJSON(b []byte) error

type PinOption

type PinOption func(cfg *pinConfig) error

PinOption is an option configuring a call to Pin.

func WithPinMeta

func WithPinMeta(key, value string) PinOption

WithPinMeta adds metadata about pinned data.

func WithPinName

func WithPinName(name string) PinOption

WithPinName sets the name to use for the pinned data.

func WithPinOrigin

func WithPinOrigin(ma string) PinOption

WithPinOrigin adds a multiaddr known to provide the data.

type PinResponse

type PinResponse struct {
	RequestID string
	Status    string
	Created   time.Time
	Pin       PinResponseDetail
	Delegates []string
}

func (*PinResponse) UnmarshalJSON

func (p *PinResponse) UnmarshalJSON(b []byte) error

type PinResponseDetail

type PinResponseDetail struct {
	Cid        cid.Cid
	SourceCid  cid.Cid
	ContentCid cid.Cid
	Name       string
	Origins    []string
	Meta       map[string]string
	Deleted    time.Time
	Created    time.Time
	Updated    time.Time
	Pins       []Pin
}

func (*PinResponseDetail) UnmarshalJSON

func (p *PinResponseDetail) UnmarshalJSON(b []byte) error

type PinStatus

type PinStatus int

func (PinStatus) String

func (s PinStatus) String() string

type PutOption

type PutOption func(cfg *putConfig) error

PutOption is an option configuring a call to Put.

func WithDirname

func WithDirname(dirname string) PutOption

WithDirname sets the root directory path, for use when the provided file is a directory and does NOT implement fs.ReadDirFile. The default is "", which will resolve to the current working directory if the file system interface is the default (the OS).

func WithFs

func WithFs(fsys fs.FS) PutOption

WithFs sets the file system interface for use with file operations.

type Status

type Status struct {
	Cid     cid.Cid
	DagSize uint64
	Created time.Time
	Pins    []Pin
	Deals   []Deal
}

Status is IPFS pin and Filecoin deal status for a given CID.

func (*Status) UnmarshalJSON

func (s *Status) UnmarshalJSON(b []byte) error

type UploadIterator

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

func (*UploadIterator) Next

func (li *UploadIterator) Next() (*Status, error)

Next retrieves status information for the next upload in the list.