package module
v0.0.7 Latest Latest

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

Go to latest
Published: Oct 17, 2022 License: Apache-2.0, MIT Imports: 24 Imported by: 23



A client to the Web3.Storage API.

Demo: https://youtu.be/FLsQZ_ogeOg


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


package main

import (

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 {

    // 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.


pkg.go.dev Reference


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


Dual-licensed under MIT + Apache 2.0




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


This section is empty.


This section is empty.


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

func (DealStatus) String

func (s DealStatus) String() string

type ListOption added in v0.0.4

type ListOption func(cfg *listConfig) error

ListOption is an option configuring a call to List.

func WithBefore added in v0.0.4

func WithBefore(before time.Time) ListOption

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

func WithMaxResults added in v0.0.4

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 added in v0.0.6

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 added in v0.0.6

type PinOption func(cfg *pinConfig) error

PinOption is an option configuring a call to Pin.

func WithPinMeta added in v0.0.6

func WithPinMeta(key, value string) PinOption

WithPinMeta adds metadata about pinned data.

func WithPinName added in v0.0.6

func WithPinName(name string) PinOption

WithPinName sets the name to use for the pinned data.

func WithPinOrigin added in v0.0.6

func WithPinOrigin(ma string) PinOption

WithPinOrigin adds a multiaddr known to provide the data.

type PinResponse added in v0.0.6

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

func (*PinResponse) UnmarshalJSON added in v0.0.6

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

type PinResponseDetail added in v0.0.6

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 added in v0.0.6

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 added in v0.0.4

type UploadIterator struct {
	// contains filtered or unexported fields

func (*UploadIterator) Next added in v0.0.4

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

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


Path Synopsis
Simplified copy of ipfs-cluster/adder/ipfsadd/add.go
Simplified copy of ipfs-cluster/adder/ipfsadd/add.go
example module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL