vcsim: add library item storage API support

govc: support Content Library iso files for cdrom backing

The 'device.cdrom.insert' and 'vm.create -iso' commands can now a URL
with 'library' scheme to back a cdrom device from a Content Library.

api: refactor 'library.info -L' functionality into library PathFinder helper.

Fixes #3213

govc/USAGE.md

@@ -1553,6 +1553,7 @@ If device is not specified, the first CD-ROM device is used.
 
 Examples:
   govc device.cdrom.insert -vm vm-1 -device cdrom-3000 images/boot.iso
+  govc device.cdrom.insert -vm vm-1 library:/boot/linux/ubuntu.iso # Content Library ISO
 
 Options:
   -device=               CD-ROM device name
@@ -3631,21 +3632,25 @@ Usage: govc library.info [OPTIONS]
 
 Display library information.
 
+Note: the '-s' flag only applies to files, not items or the library itself.
+
 Examples:
   govc library.info
   govc library.info /lib1
   govc library.info -l /lib1 | grep Size:
   govc library.info /lib1/item1
   govc library.info /lib1/item1/
   govc library.info */
-  govc device.cdrom.insert -vm $vm -device cdrom-3000 $(govc library.info -L /lib1/item1/file1)
+  govc library.info -L /lib1/item1/file1 # file path relative to Datastore
+  govc library.info -L -l /lib1/item1/file1 # file path including Datastore
   govc library.info -json | jq .
   govc library.info -json /lib1/item1 | jq .
 
 Options:
   -L=false               List Datastore path only
   -U=false               List pub/sub URL(s) only
   -l=false               Long listing format
+  -s=false               Include file specific storage details
 ```
 
 ## library.ls
@@ -6284,6 +6289,7 @@ https://code.vmware.com/apis/358/vsphere/doc/vim.vm.GuestOsDescriptor.GuestOsIde
 
 Examples:
   govc vm.create -on=false vm-name
+  govc vm.create -iso library:/boot/linux/ubuntu.iso vm-name # Content Library ISO
   govc vm.create -cluster cluster1 vm-name # use compute cluster placement
   govc vm.create -datastore-cluster dscluster vm-name # use datastore cluster placement
   govc vm.create -m 2048 -c 2 -g freebsd64Guest -net.adapter vmxnet3 -disk.controller pvscsi vm-name

govc/device/cdrom/insert.go

@@ -1,11 +1,11 @@
 /*
-Copyright (c) 2014-2016 VMware, Inc. All Rights Reserved.
+Copyright (c) 2014-2024 VMware, Inc. All Rights Reserved.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at
 
-    http://www.apache.org/licenses/LICENSE-2.0
+http://www.apache.org/licenses/LICENSE-2.0
 
 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
@@ -64,7 +64,8 @@ func (cmd *insert) Description() string {
 If device is not specified, the first CD-ROM device is used.
 
 Examples:
-  govc device.cdrom.insert -vm vm-1 -device cdrom-3000 images/boot.iso`
+  govc device.cdrom.insert -vm vm-1 -device cdrom-3000 images/boot.iso
+  govc device.cdrom.insert -vm vm-1 library:/boot/linux/ubuntu.iso # Content Library ISO`
 }
 
 func (cmd *insert) Run(ctx context.Context, f *flag.FlagSet) error {
@@ -87,7 +88,7 @@ func (cmd *insert) Run(ctx context.Context, f *flag.FlagSet) error {
 		return err
 	}
 
-	iso, err := cmd.DatastorePath(f.Arg(0))
+	iso, err := cmd.FileBacking(ctx, f.Arg(0), false)
 	if err != nil {
 		return err
 	}

govc/flags/datastore.go

@@ -1,11 +1,11 @@
 /*
-Copyright (c) 2014-2016 VMware, Inc. All Rights Reserved.
+Copyright (c) 2014-2024 VMware, Inc. All Rights Reserved.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at
 
-    http://www.apache.org/licenses/LICENSE-2.0
+http://www.apache.org/licenses/LICENSE-2.0
 
 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
@@ -20,9 +20,12 @@ import (
 	"context"
 	"flag"
 	"fmt"
+	"net/url"
 	"os"
 
 	"github.com/vmware/govmomi/object"
+	"github.com/vmware/govmomi/vapi/library"
+	"github.com/vmware/govmomi/vapi/library/finder"
 	"github.com/vmware/govmomi/vim25/types"
 )
 
@@ -148,3 +151,59 @@ func (f *DatastoreFlag) Stat(ctx context.Context, file string) (types.BaseFileIn
 	return ds.Stat(ctx, file)
 
 }
+
+func (f *DatastoreFlag) libraryPath(ctx context.Context, p string) (string, error) {
+	vc, err := f.Client()
+	if err != nil {
+		return "", err
+	}
+
+	rc, err := f.RestClient()
+	if err != nil {
+		return "", err
+	}
+
+	m := library.NewManager(rc)
+
+	r, err := finder.NewFinder(m).Find(ctx, p)
+	if err != nil {
+		return "", err
+	}
+
+	if len(r) != 1 {
+		return "", fmt.Errorf("%s: %d found", p, len(r))
+	}
+
+	return finder.NewPathFinder(m, vc).Path(ctx, r[0])
+}
+
+// FileBacking converts the given file path for use as VirtualDeviceFileBackingInfo.FileName.
+func (f *DatastoreFlag) FileBacking(ctx context.Context, file string, stat bool) (string, error) {
+	u, err := url.Parse(file)
+	if err != nil {
+		return "", err
+	}
+
+	switch u.Scheme {
+	case "library":
+		return f.libraryPath(ctx, u.Path)
+	case "ds":
+		// datastore url, e.g. ds:///vmfs/volumes/$uuid/...
+		return file, nil
+	}
+
+	var p object.DatastorePath
+	if p.FromString(file) {
+		// datastore is specified
+		return file, nil
+	}
+
+	if stat {
+		// Verify ISO exists
+		if _, err := f.Stat(ctx, file); err != nil {
+			return "", err
+		}
+	}
+
+	return f.DatastorePath(file)
+}