feat: support for optional pin names

client/rpc/pin.go

@@ -26,6 +26,7 @@ type pinRefKeyList struct {
 type pin struct {
 	path path.ImmutablePath
 	typ  string
+	name string
 	err  error
 }
 
@@ -37,6 +38,10 @@ func (p pin) Path() path.ImmutablePath {
 	return p.path
 }
 
+func (p pin) Name() string {
+	return p.name
+}
+
 func (p pin) Type() string {
 	return p.typ
 }
@@ -53,6 +58,7 @@ func (api *PinAPI) Add(ctx context.Context, p path.Path, opts ...caopts.PinAddOp
 
 type pinLsObject struct {
 	Cid  string
+	Name string
 	Type string
 }
 
@@ -102,7 +108,7 @@ func (api *PinAPI) Ls(ctx context.Context, opts ...caopts.PinLsOption) (<-chan i
 			}
 
 			select {
-			case ch <- pin{typ: out.Type, path: path.FromCid(c)}:
+			case ch <- pin{typ: out.Type, name: out.Name, path: path.FromCid(c)}:
 			case <-ctx.Done():
 				return
 			}

cmd/ipfs/kubo/init.go

@@ -252,7 +252,7 @@ func initializeIpnsKeyspace(repoRoot string) error {
 
 	// pin recursively because this might already be pinned
 	// and doing a direct pin would throw an error in that case
-	err = nd.Pinning.Pin(ctx, emptyDir, true)
+	err = nd.Pinning.Pin(ctx, emptyDir, true, "")
 	if err != nil {
 		return err
 	}

core/commands/dag/import.go

@@ -152,7 +152,7 @@ func dagImport(req *cmds.Request, res cmds.ResponseEmitter, env cmds.Environment
 				ret.PinErrorMsg = err.Error()
 			} else if nd, err := blockDecoder.DecodeNode(req.Context, block); err != nil {
 				ret.PinErrorMsg = err.Error()
-			} else if err := node.Pinning.Pin(req.Context, nd, true); err != nil {
+			} else if err := node.Pinning.Pin(req.Context, nd, true, ""); err != nil {
 				ret.PinErrorMsg = err.Error()
 			} else if err := node.Pinning.Flush(req.Context); err != nil {
 				ret.PinErrorMsg = err.Error()

core/commands/pin/pin.go

@@ -65,6 +65,7 @@ var addPinCmd = &cmds.Command{
 	Options: []cmds.Option{
 		cmds.BoolOption(pinRecursiveOptionName, "r", "Recursively pin the object linked to by the specified object(s).").WithDefault(true),
 		cmds.BoolOption(pinProgressOptionName, "Show progress"),
+		cmds.StringOption(pinNameOptionName, "n", "An optional name for the pin(s)."),
 	},
 	Type: AddPinOutput{},
 	Run: func(req *cmds.Request, res cmds.ResponseEmitter, env cmds.Environment) error {
@@ -75,6 +76,7 @@ var addPinCmd = &cmds.Command{
 
 		// set recursive flag
 		recursive, _ := req.Options[pinRecursiveOptionName].(bool)
+		name, _ := req.Options[pinNameOptionName].(string)
 		showProgress, _ := req.Options[pinProgressOptionName].(bool)
 
 		if err := req.ParseBodyArgs(); err != nil {
@@ -87,7 +89,7 @@ var addPinCmd = &cmds.Command{
 		}
 
 		if !showProgress {
-			added, err := pinAddMany(req.Context, api, enc, req.Arguments, recursive)
+			added, err := pinAddMany(req.Context, api, enc, req.Arguments, recursive, name)
 			if err != nil {
 				return err
 			}
@@ -105,7 +107,7 @@ var addPinCmd = &cmds.Command{
 
 		ch := make(chan pinResult, 1)
 		go func() {
-			added, err := pinAddMany(ctx, api, enc, req.Arguments, recursive)
+			added, err := pinAddMany(ctx, api, enc, req.Arguments, recursive, name)
 			ch <- pinResult{pins: added, err: err}
 		}()
 
@@ -181,7 +183,7 @@ var addPinCmd = &cmds.Command{
 	},
 }
 
-func pinAddMany(ctx context.Context, api coreiface.CoreAPI, enc cidenc.Encoder, paths []string, recursive bool) ([]string, error) {
+func pinAddMany(ctx context.Context, api coreiface.CoreAPI, enc cidenc.Encoder, paths []string, recursive bool, name string) ([]string, error) {
 	added := make([]string, len(paths))
 	for i, b := range paths {
 		p, err := cmdutils.PathOrCidPath(b)
@@ -194,7 +196,7 @@ func pinAddMany(ctx context.Context, api coreiface.CoreAPI, enc cidenc.Encoder,
 			return nil, err
 		}
 
-		if err := api.Pin().Add(ctx, rp, options.Pin.Recursive(recursive)); err != nil {
+		if err := api.Pin().Add(ctx, rp, options.Pin.Recursive(recursive), options.Pin.Name(name)); err != nil {
 			return nil, err
 		}
 		added[i] = enc.Encode(rp.RootCid())
@@ -356,7 +358,7 @@ Example:
 		lgcList := map[string]PinLsType{}
 		if !stream {
 			emit = func(v PinLsOutputWrapper) error {
-				lgcList[v.PinLsObject.Cid] = PinLsType{Type: v.PinLsObject.Type}
+				lgcList[v.PinLsObject.Cid] = PinLsType{Type: v.PinLsObject.Type, Label: v.PinLsObject.Name}
 				return nil
 			}
 		} else {
@@ -402,17 +404,21 @@ Example:
 			if stream {
 				if quiet {
 					fmt.Fprintf(w, "%s\n", out.PinLsObject.Cid)
-				} else {
+				} else if out.PinLsObject.Name == "" {
 					fmt.Fprintf(w, "%s %s\n", out.PinLsObject.Cid, out.PinLsObject.Type)
+				} else {
+					fmt.Fprintf(w, "%s %s %s\n", out.PinLsObject.Cid, out.PinLsObject.Type, out.PinLsObject.Name)
 				}
 				return nil
 			}
 
 			for k, v := range out.PinLsList.Keys {
 				if quiet {
 					fmt.Fprintf(w, "%s\n", k)
-				} else {
+				} else if v.Label == "" {
 					fmt.Fprintf(w, "%s %s\n", k, v.Type)
+				} else {
+					fmt.Fprintf(w, "%s %s %s\n", k, v.Type, v.Label)
 				}
 			}
 
@@ -436,12 +442,14 @@ type PinLsList struct {
 
 // PinLsType contains the type of a pin
 type PinLsType struct {
-	Type string
+	Type  string
+	Label string
 }
 
 // PinLsObject contains the description of a pin
 type PinLsObject struct {
 	Cid  string `json:",omitempty"`
+	Name string `json:",omitempty"`
 	Type string `json:",omitempty"`
 }
 
@@ -532,6 +540,7 @@ func pinLsAll(req *cmds.Request, typeStr string, api coreiface.CoreAPI, emit fun
 		err = emit(PinLsOutputWrapper{
 			PinLsObject: PinLsObject{
 				Type: p.Type(),
+				Name: p.Name(),
 				Cid:  enc.Encode(p.Path().RootCid()),
 			},
 		})
@@ -753,10 +762,10 @@ func pinVerify(ctx context.Context, n *core.IpfsNode, opts pinVerifyOpts, enc ci
 				out <- PinVerifyRes{Err: p.Err.Error()}
 				return
 			}
-			pinStatus := checkPin(p.C)
+			pinStatus := checkPin(p.Pin.Key)
 			if !pinStatus.Ok || opts.includeOk {
 				select {
-				case out <- PinVerifyRes{Cid: enc.Encode(p.C), PinStatus: pinStatus}:
+				case out <- PinVerifyRes{Cid: enc.Encode(p.Pin.Key), PinStatus: pinStatus}:
 				case <-ctx.Done():
 					return
 				}

core/coreapi/block.go

@@ -60,7 +60,7 @@ func (api *BlockAPI) Put(ctx context.Context, src io.Reader, opts ...caopts.Bloc
 	}
 
 	if settings.Pin {
-		if err = api.pinning.PinWithMode(ctx, b.Cid(), pin.Recursive); err != nil {
+		if err = api.pinning.PinWithMode(ctx, b.Cid(), pin.Recursive, ""); err != nil {
 			return nil, err
 		}
 		if err := api.pinning.Flush(ctx); err != nil {

core/coreapi/dag.go

@@ -30,7 +30,7 @@ func (adder *pinningAdder) Add(ctx context.Context, nd ipld.Node) error {
 		return err
 	}
 
-	if err := adder.pinning.PinWithMode(ctx, nd.Cid(), pin.Recursive); err != nil {
+	if err := adder.pinning.PinWithMode(ctx, nd.Cid(), pin.Recursive, ""); err != nil {
 		return err
 	}
 
@@ -51,7 +51,7 @@ func (adder *pinningAdder) AddMany(ctx context.Context, nds []ipld.Node) error {
 	for _, nd := range nds {
 		c := nd.Cid()
 		if cids.Visit(c) {
-			if err := adder.pinning.PinWithMode(ctx, c, pin.Recursive); err != nil {
+			if err := adder.pinning.PinWithMode(ctx, c, pin.Recursive, ""); err != nil {
 				return err
 			}
 		}

core/coreapi/object.go

@@ -133,7 +133,7 @@ func (api *ObjectAPI) Put(ctx context.Context, src io.Reader, opts ...caopts.Obj
 	}
 
 	if options.Pin {
-		if err := api.pinning.PinWithMode(ctx, dagnode.Cid(), pin.Recursive); err != nil {
+		if err := api.pinning.PinWithMode(ctx, dagnode.Cid(), pin.Recursive, ""); err != nil {
 			return path.ImmutablePath{}, err
 		}
 

core/coreapi/pin.go

@@ -38,7 +38,7 @@ func (api *PinAPI) Add(ctx context.Context, p path.Path, opts ...caopts.PinAddOp
 
 	defer api.blockstore.PinLock(ctx).Unlock(ctx)
 
-	err = api.pinning.Pin(ctx, dagNode, settings.Recursive)
+	err = api.pinning.Pin(ctx, dagNode, settings.Recursive, settings.Name)
 	if err != nil {
 		return fmt.Errorf("pin: %s", err)
 	}
@@ -236,7 +236,7 @@ func (api *PinAPI) Verify(ctx context.Context) (<-chan coreiface.PinStatus, erro
 			if p.Err != nil {
 				res = &pinStatus{err: p.Err}
 			} else {
-				res = checkPin(p.C)
+				res = checkPin(p.Pin.Key)
 			}
 			select {
 			case <-ctx.Done():
@@ -252,6 +252,7 @@ func (api *PinAPI) Verify(ctx context.Context) (<-chan coreiface.PinStatus, erro
 type pinInfo struct {
 	pinType string
 	path    path.ImmutablePath
+	name    string
 	err     error
 }
 
@@ -263,6 +264,10 @@ func (p *pinInfo) Type() string {
 	return p.pinType
 }
 
+func (p *pinInfo) Name() string {
+	return p.name
+}
+
 func (p *pinInfo) Err() error {
 	return p.err
 }
@@ -276,11 +281,12 @@ func (api *PinAPI) pinLsAll(ctx context.Context, typeStr string) <-chan coreifac
 
 	emittedSet := cid.NewSet()
 
-	AddToResultKeys := func(c cid.Cid, typeStr string) error {
+	AddToResultKeys := func(c cid.Cid, name, typeStr string) error {
 		if emittedSet.Visit(c) {
 			select {
 			case out <- &pinInfo{
 				pinType: typeStr,
+				name:    name,
 				path:    path.FromCid(c),
 			}:
 			case <-ctx.Done():
@@ -301,11 +307,11 @@ func (api *PinAPI) pinLsAll(ctx context.Context, typeStr string) <-chan coreifac
 					out <- &pinInfo{err: streamedCid.Err}
 					return
 				}
-				if err = AddToResultKeys(streamedCid.C, "recursive"); err != nil {
+				if err = AddToResultKeys(streamedCid.Pin.Key, streamedCid.Pin.Name, "recursive"); err != nil {
 					out <- &pinInfo{err: err}
 					return
 				}
-				rkeys = append(rkeys, streamedCid.C)
+				rkeys = append(rkeys, streamedCid.Pin.Key)
 			}
 		}
 		if typeStr == "direct" || typeStr == "all" {
@@ -314,7 +320,7 @@ func (api *PinAPI) pinLsAll(ctx context.Context, typeStr string) <-chan coreifac
 					out <- &pinInfo{err: streamedCid.Err}
 					return
 				}
-				if err = AddToResultKeys(streamedCid.C, "direct"); err != nil {
+				if err = AddToResultKeys(streamedCid.Pin.Key, streamedCid.Pin.Name, "direct"); err != nil {
 					out <- &pinInfo{err: err}
 					return
 				}
@@ -329,16 +335,16 @@ func (api *PinAPI) pinLsAll(ctx context.Context, typeStr string) <-chan coreifac
 					out <- &pinInfo{err: streamedCid.Err}
 					return
 				}
-				emittedSet.Add(streamedCid.C)
+				emittedSet.Add(streamedCid.Pin.Key)
 			}
 
 			for streamedCid := range api.pinning.RecursiveKeys(ctx) {
 				if streamedCid.Err != nil {
 					out <- &pinInfo{err: streamedCid.Err}
 					return
 				}
-				emittedSet.Add(streamedCid.C)
-				rkeys = append(rkeys, streamedCid.C)
+				emittedSet.Add(streamedCid.Pin.Key)
+				rkeys = append(rkeys, streamedCid.Pin.Key)
 			}
 		}
 		if typeStr == "indirect" || typeStr == "all" {
@@ -353,7 +359,7 @@ func (api *PinAPI) pinLsAll(ctx context.Context, typeStr string) <-chan coreifac
 						if emittedSet.Has(c) {
 							return true // skipped
 						}
-						err := AddToResultKeys(c, "indirect")
+						err := AddToResultKeys(c, "", "indirect")
 						if err != nil {
 							out <- &pinInfo{err: err}
 							return false

core/coreiface/options/pin.go

@@ -5,6 +5,7 @@ import "fmt"
 // PinAddSettings represent the settings for PinAPI.Add
 type PinAddSettings struct {
 	Recursive bool
+	Name      string
 }
 
 // PinLsSettings represent the settings for PinAPI.Ls
@@ -263,6 +264,14 @@ func (pinOpts) Recursive(recursive bool) PinAddOption {
 	}
 }
 
+// Name is an option for Pin.Add which specifies an optional name to add to the pin.
+func (pinOpts) Name(name string) PinAddOption {
+	return func(settings *PinAddSettings) error {
+		settings.Name = name
+		return nil
+	}
+}
+
 // RmRecursive is an option for Pin.Rm which specifies whether to recursively
 // unpin the object linked to by the specified object(s). This does not remove
 // indirect pins referenced by other recursive pins.

core/coreiface/pin.go

@@ -13,6 +13,9 @@ type Pin interface {
 	// Path to the pinned object
 	Path() path.ImmutablePath
 
+	// Name is the name of the pin.
+	Name() string
+
 	// Type of the pin
 	Type() string
 

core/coreunix/add.go

@@ -186,7 +186,7 @@ func (adder *Adder) PinRoot(ctx context.Context, root ipld.Node) error {
 		adder.tempRoot = rnk
 	}
 
-	err = adder.pinning.PinWithMode(ctx, rnk, pin.Recursive)
+	err = adder.pinning.PinWithMode(ctx, rnk, pin.Recursive, "")
 	if err != nil {
 		return err
 	}

docs/examples/kubo-as-a-library/go.mod

@@ -7,7 +7,7 @@ go 1.20
 replace github.com/ipfs/kubo => ./../../..
 
 require (
-	github.com/ipfs/boxo v0.16.0
+	github.com/ipfs/boxo v0.16.1-0.20240102112808-a73b1877dbf8
 	github.com/ipfs/kubo v0.0.0-00010101000000-000000000000
 	github.com/libp2p/go-libp2p v0.32.2
 	github.com/multiformats/go-multiaddr v0.12.0

docs/examples/kubo-as-a-library/go.sum

@@ -303,8 +303,8 @@ github.com/ipfs-shipyard/nopfs/ipfs v0.13.2-0.20231027223058-cde3b5ba964c h1:7Uy
 github.com/ipfs-shipyard/nopfs/ipfs v0.13.2-0.20231027223058-cde3b5ba964c/go.mod h1:6EekK/jo+TynwSE/ZOiOJd4eEvRXoavEC3vquKtv4yI=
 github.com/ipfs/bbloom v0.0.4 h1:Gi+8EGJ2y5qiD5FbsbpX/TMNcJw8gSqr7eyjHa4Fhvs=
 github.com/ipfs/bbloom v0.0.4/go.mod h1:cS9YprKXpoZ9lT0n/Mw/a6/aFV6DTjTLYHeA+gyqMG0=
-github.com/ipfs/boxo v0.16.0 h1:A9dUmef5a+mEFki6kbyG7el5gl65CiUBzrDeZxzTWKY=
-github.com/ipfs/boxo v0.16.0/go.mod h1:jAgpNQn7T7BnibUeReXcKU9Ha1xmYNyOlwVEl193ow0=
+github.com/ipfs/boxo v0.16.1-0.20240102112808-a73b1877dbf8 h1:J7v8ilV3rJDSFuEIIfQfEwqYBrdoksTenVRdpUzrpiU=
+github.com/ipfs/boxo v0.16.1-0.20240102112808-a73b1877dbf8/go.mod h1:jAgpNQn7T7BnibUeReXcKU9Ha1xmYNyOlwVEl193ow0=
 github.com/ipfs/go-bitfield v1.1.0 h1:fh7FIo8bSwaJEh6DdTWbCeZ1eqOaOkKFI74SCnsWbGA=
 github.com/ipfs/go-bitfield v1.1.0/go.mod h1:paqf1wjq/D2BBmzfTVFlJQ9IlFOZpg422HL0HqsGWHU=
 github.com/ipfs/go-block-format v0.0.2/go.mod h1:AWR46JfpcObNfg3ok2JHDUfdiHRgWhJgCQF+KIgOPJY=

fuse/ipns/common.go

@@ -18,7 +18,7 @@ func InitializeKeyspace(n *core.IpfsNode, key ci.PrivKey) error {
 
 	emptyDir := ft.EmptyDirNode()
 
-	err := n.Pinning.Pin(ctx, emptyDir, false)
+	err := n.Pinning.Pin(ctx, emptyDir, false, "")
 	if err != nil {
 		return err
 	}