ipfs pin

[jbenet]

ipfs needs a way to pin (keep around) specific objects. This needs to work with:

• (perhaps!) an underlying function on the Blockstore, so clients can use it / query it
• a function on the ipfs interface (ipfs node, for now), for programmatic use.
• a command, to specify objects to pin from cli or http, etc.

We'll need to store a set of "pin records" or "pin refs", that tell us which objects are pinned or not. For efficiency, this should porbably be in the datastore, under a well-known key, like pin/list, (note datastore keys
cann be namespaced, etc). Could also be in it its own file $IPFS_DIR/pin.

A pin record looks like

type pinType int
enum  (
  pinDirectly pinType = iota,
  pinIndirectly,
  pinRecursively,
)

type pinRecord struct {
  // The key to pin
  key string

  // whether direct, indirect, recusrive, etc.
  type pinType
}

There probably are some configuration constraints:

• whether to auto-pin objects you add with ipfs add

// Pinning is the set of config options for object pinning.
type Pinning struct {
  // whether local node should pin files added with local commands
  // like `ipfs add`.
  Autopin string
}

I'll describe here how the cli command should look. The help should look like:

  UsageLine: "pin",
  Short:     "Object persistence",
  Long: `ipfs pin - Object persistence

    ipfs pin add [-r] <ref> - Pin a particular object
    ipfs pin rm [-r] <ref>  - Remove a pin reference
    ipfs pin list           - Show the pin ref list.

IPFS "pins" objects to make sure they stick around, and are not
evicted from the object cache on garbage collection. This command
helps manage the node's pinned references. <ref> means any ipfs ref,
a key (hash), a path, etc.

`,

The command should work like

# pin a specific object
> ipfs pin add Qmambmabambmamba
pinned Qmambmabambmamba direct
> ipfs pin add Qmewqeqrewqrqreq
pinned Qmewqeqrewqrqreq direct

# pin all an object, and all its children
# note that the pin ref only made for top level node
> ipfs pin add -r Qmambmabambmamba
pinned Qmvcxzvcmvncxmvn indirect
pinned Qmewqeqrewqrqreq indirect
pinned Qmambmabambmamba recursive

# show a list of pinned records
> ipfs pin list
Qmvcxzvcmvncxmvn indirect
Qmewqeqrewqrqreq direct
Qmambmabambmamba recursive

# remove an object pin record (only the one specified by key)
> ipfs pin rm Qmambmabambmamba
unpinned Qmambmabambmamba

# remove all object records
> ipfs pin rm -r Qmambmabambmamba
unpinned Qmvcxzvcmvncxmvn indirect
unpinned Qmewqeqrewqrqreq direct
unpinned Qmambmabambmamba recursive

Or something like that.