pin

README

go-ipfs-pinner

❗ This repo is no longer maintained.

👉 We highly recommend switching to the maintained version at https://github.com/ipfs/boxo/tree/main/pinning/pinner. 🏎️ Good news! There is tooling and documentation to expedite a switch in your repo.

⚠️ If you continue using this repo, please note that security fixes will not be provided (unless someone steps in to maintain it).

📚 Learn more, including how to take the maintainership mantle or ask questions, here.

Background

The pinner system is responsible for keeping track of which objects a user wants to keep stored locally

Install

Via go get:

$ go get github.com/ipfs/go-ipfs-pinner

Requires Go 1.13

Documentation

https://godoc.org/github.com/ipfs/go-ipfs-pinner

License

This library is dual-licensed under Apache 2.0 and MIT terms.

Copyright 2019. Protocol Labs, Inc.

Documentation

Overview

Package pin implements structures and methods to keep track of which objects a user wants to keep stored locally.

Index

• Variables
• func ModeToString(mode Mode) (string, bool)
• type Mode
  • func StringToMode(s string) (Mode, bool)
• type Pinned
  • func (p Pinned) Pinned() bool
  • func (p Pinned) String() string
• type Pinner

Variables

var ErrNotPinned = fmt.Errorf("not pinned or pinned indirectly")

ErrNotPinned is returned when trying to unpin items that are not pinned.

Deprecated: use github.com/ipfs/boxo/pinning/pinner.ErrNotPinned

Functions

func ModeToString

func ModeToString(mode Mode) (string, bool)

ModeToString returns a human-readable name for the Mode.

Deprecated: use github.com/ipfs/boxo/pinning/pinner.ModeToString

Types

type Mode

type Mode int

Mode allows to specify different types of pin (recursive, direct etc.). See the Pin Modes constants for a full list.

Deprecated: use github.com/ipfs/boxo/pinning/pinner.Mode

const (
	// Recursive pins pin the target cids along with any reachable children.
	//
	// Deprecated: use github.com/ipfs/boxo/pinning/pinner.Recursive
	Recursive Mode = iota

	// Direct pins pin just the target cid.
	//
	// Deprecated: use github.com/ipfs/boxo/pinning/pinner.Direct
	Direct

	// Indirect pins are cids who have some ancestor pinned recursively.
	//
	// Deprecated: use github.com/ipfs/boxo/pinning/pinner.Indirect
	Indirect

	// Internal pins are cids used to keep the internal state of the pinner.
	//
	// Deprecated: use github.com/ipfs/boxo/pinning/pinner.Internal
	Internal

	// NotPinned
	//
	// Deprecated: use github.com/ipfs/boxo/pinning/pinner.NotPinned
	NotPinned

	// Any refers to any pinned cid
	//
	// Deprecated: use github.com/ipfs/boxo/pinning/pinner.Any
	Any
)

Pin Modes

func StringToMode

func StringToMode(s string) (Mode, bool)

StringToMode parses the result of ModeToString() back to a Mode. It returns a boolean which is set to false if the mode is unknown.

Deprecated: use github.com/ipfs/boxo/pinning/pinner.StringToMode

type Pinned

type Pinned struct {
	Key  cid.Cid
	Mode Mode
	Via  cid.Cid
}

Pinned represents CID which has been pinned with a pinning strategy. The Via field allows to identify the pinning parent of this CID, in the case that the item is not pinned directly (but rather pinned recursively by some ascendant).

Deprecated: use github.com/ipfs/boxo/pinning/pinner.Pinned

func (Pinned) Pinned

func (p Pinned) Pinned() bool

Pinned returns whether or not the given cid is pinned

func (Pinned) String

func (p Pinned) String() string

String Returns pin status as string

type Pinner

type Pinner interface {
	// IsPinned returns whether or not the given cid is pinned
	// and an explanation of why its pinned
	IsPinned(ctx context.Context, c cid.Cid) (string, bool, error)

	// IsPinnedWithType returns whether or not the given cid is pinned with the
	// given pin type, as well as returning the type of pin its pinned with.
	IsPinnedWithType(ctx context.Context, c cid.Cid, mode Mode) (string, bool, error)

	// Pin the given node, optionally recursively.
	// Pin will make sure that the given node and its children if recursive is set
	// are stored locally.
	Pin(ctx context.Context, node ipld.Node, recursive bool) error

	// Unpin the given cid. If recursive is true, removes either a recursive or
	// a direct pin. If recursive is false, only removes a direct pin.
	// If the pin doesn't exist, return ErrNotPinned
	Unpin(ctx context.Context, cid cid.Cid, recursive bool) error

	// Update updates a recursive pin from one cid to another
	// this is more efficient than simply pinning the new one and unpinning the
	// old one
	Update(ctx context.Context, from, to cid.Cid, unpin bool) error

	// Check if a set of keys are pinned, more efficient than
	// calling IsPinned for each key
	CheckIfPinned(ctx context.Context, cids ...cid.Cid) ([]Pinned, error)

	// PinWithMode is for manually editing the pin structure. Use with
	// care! If used improperly, garbage collection may not be
	// successful.
	PinWithMode(context.Context, cid.Cid, Mode) error

	// Flush writes the pin state to the backing datastore
	Flush(ctx context.Context) error

	// DirectKeys returns all directly pinned cids
	DirectKeys(ctx context.Context) ([]cid.Cid, error)

	// RecursiveKeys returns all recursively pinned cids
	RecursiveKeys(ctx context.Context) ([]cid.Cid, error)

	// InternalPins returns all cids kept pinned for the internal state of the
	// pinner
	InternalPins(ctx context.Context) ([]cid.Cid, error)
}

A Pinner provides the necessary methods to keep track of Nodes which are to be kept locally, according to a pin mode. In practice, a Pinner is in in charge of keeping the list of items from the local storage that should not be garbage-collected.

Deprecated: use github.com/ipfs/boxo/pinning/pinner.Pinner