Refactor manifest list operations

* Update method/function signatures use the manifest list name and
  images associated with the operation explicitly, in general

  func f(ctx context.Context, manifestListName string,
         ImageNames []string, options *fOptions)

* Leverage gorilla/mux Subrouters to support API v3.x and v4.x for
  manifests
* Make manifest API endpoints more RESTful
* Add PUT /manifest/{id} to update existing manifests
* Add manifests.Annotate to go bindings, uncommented unit test
* Add DELETE /manifest/{Id} to remove existing manifest list, use
  PUT /manifest/{id} to remove images from a list
* Deprecated POST /manifest/{id}/add and /manifest/{id}/remove, use
  PUT /manifest/{id} instead
* Corrected swagger godoc and updated to cover API changes
* Update podman manifest commands to use registry.Context()
* Expose utils.GetVar() to obtain query parameters by name
* Unexpose server.registerSwaggerHandlers, not sure why this was ever
  exposed.
* Refactored code to use http.Header instead of map[string]string when
  operating on HTTP headers.
* Add API-Version header support in bindings to allow calling explicate
  versions of the API. Header is _NOT_ forwarded to the API service.

Signed-off-by: Jhon Honce <jhonce@redhat.com>

3 files changed, 70 insertions, 26 deletions

diff --git a/pkg/domain/entities/engine_image.go b/pkg/domain/entities/engine_image.go
index bec505163..bf9fcfd27 100644
--- a/pkg/domain/entities/engine_image.go
+++ b/pkg/domain/entities/engine_image.go
@@ -31,12 +31,12 @@ type ImageEngine interface {
 	Tree(ctx context.Context, nameOrID string, options ImageTreeOptions) (*ImageTreeReport, error)
 	Unmount(ctx context.Context, images []string, options ImageUnmountOptions) ([]*ImageUnmountReport, error)
 	Untag(ctx context.Context, nameOrID string, tags []string, options ImageUntagOptions) error
-	ManifestCreate(ctx context.Context, names, images []string, opts ManifestCreateOptions) (string, error)
+	ManifestCreate(ctx context.Context, name string, images []string, opts ManifestCreateOptions) (string, error)
 	ManifestExists(ctx context.Context, name string) (*BoolReport, error)
 	ManifestInspect(ctx context.Context, name string) ([]byte, error)
-	ManifestAdd(ctx context.Context, opts ManifestAddOptions) (string, error)
-	ManifestAnnotate(ctx context.Context, names []string, opts ManifestAnnotateOptions) (string, error)
-	ManifestRemove(ctx context.Context, names []string) (string, error)
+	ManifestAdd(ctx context.Context, listName string, imageNames []string, opts ManifestAddOptions) (string, error)
+	ManifestAnnotate(ctx context.Context, names, image string, opts ManifestAnnotateOptions) (string, error)
+	ManifestRemoveDigest(ctx context.Context, names, image string) (string, error)
 	ManifestRm(ctx context.Context, names []string) (*ImageRemoveReport, []error)
 	ManifestPush(ctx context.Context, name, destination string, imagePushOpts ImagePushOptions) (string, error)
 	Sign(ctx context.Context, names []string, options SignOptions) (*SignReport, error)
diff --git a/pkg/domain/entities/images.go b/pkg/domain/entities/images.go
index 62e7f67c8..bc41d7844 100644
--- a/pkg/domain/entities/images.go
+++ b/pkg/domain/entities/images.go
@@ -94,7 +94,7 @@ type ImageRemoveOptions struct {
 	LookupManifest bool
 }
 
-// ImageRemoveResponse is the response for removing one or more image(s) from storage
+// ImageRemoveReport is the response for removing one or more image(s) from storage
 // and images what was untagged vs actually removed.
 type ImageRemoveReport struct {
 	// Deleted images.
diff --git a/pkg/domain/entities/manifest.go b/pkg/domain/entities/manifest.go
index 3f89e4d30..81f3e837b 100644
--- a/pkg/domain/entities/manifest.go
+++ b/pkg/domain/entities/manifest.go
@@ -2,35 +2,79 @@ package entities
 
 import "github.com/containers/image/v5/types"
 
-// TODO: add comments to *all* types and fields.
-
+// ManifestCreateOptions provides model for creating manifest
 type ManifestCreateOptions struct {
 	All bool `schema:"all"`
 }
 
-// swagger:model ManifestAddOpts
+// ManifestAddOptions provides model for adding digests to manifest list
+//
+// swagger:model
 type ManifestAddOptions struct {
-	All           bool               `json:"all" schema:"all"`
-	Annotation    []string           `json:"annotation" schema:"annotation"`
-	Arch          string             `json:"arch" schema:"arch"`
-	Authfile      string             `json:"-" schema:"-"`
-	CertDir       string             `json:"-" schema:"-"`
-	Features      []string           `json:"features" schema:"features"`
-	Images        []string           `json:"images" schema:"images"`
-	OS            string             `json:"os" schema:"os"`
-	OSVersion     string             `json:"os_version" schema:"os_version"`
-	Password      string             `json:"-" schema:"-"`
+	ManifestAnnotateOptions
+	// True when operating on a list to include all images
+	All bool `json:"all" schema:"all"`
+	// authfile to use when pushing manifest list
+	Authfile string `json:"-" schema:"-"`
+	// Home directory for certificates when pushing a manifest list
+	CertDir string `json:"-" schema:"-"`
+	// Password to authenticate to registry when pushing manifest list
+	Password string `json:"-" schema:"-"`
+	// Should TLS registry certificate be verified?
 	SkipTLSVerify types.OptionalBool `json:"-" schema:"-"`
-	Username      string             `json:"-" schema:"-"`
-	Variant       string             `json:"variant" schema:"variant"`
+	// Username to authenticate to registry when pushing manifest list
+	Username string `json:"-" schema:"-"`
+	// Images is an optional list of images to add to manifest list
+	Images []string `json:"images" schema:"images"`
 }
 
+// ManifestAnnotateOptions provides model for annotating manifest list
 type ManifestAnnotateOptions struct {
-	Annotation []string `json:"annotation"`
-	Arch       string   `json:"arch" schema:"arch"`
-	Features   []string `json:"features" schema:"features"`
-	OS         string   `json:"os" schema:"os"`
+	// Annotation to add to manifest list
+	Annotation []string `json:"annotation" schema:"annotation"`
+	// Arch overrides the architecture for the image
+	Arch string `json:"arch" schema:"arch"`
+	// Feature list for the image
+	Features []string `json:"features" schema:"features"`
+	// OS overrides the operating system for the image
+	OS string `json:"os" schema:"os"`
+	// OS features for the image
 	OSFeatures []string `json:"os_features" schema:"os_features"`
-	OSVersion  string   `json:"os_version" schema:"os_version"`
-	Variant    string   `json:"variant" schema:"variant"`
+	// OSVersion overrides the operating system for the image
+	OSVersion string `json:"os_version" schema:"os_version"`
+	// Variant for the image
+	Variant string `json:"variant" schema:"variant"`
+}
+
+// ManifestModifyOptions provides the model for mutating a manifest
+//
+// swagger 2.0 does not support oneOf for schema validation.
+//
+// Operation "update" uses all fields.
+// Operation "remove" uses fields: Operation and Images
+// Operation "annotate" uses fields: Operation and Annotations
+//
+// swagger:model
+type ManifestModifyOptions struct {
+	Operation string `json:"operation" schema:"operation"` // Valid values: update, remove, annotate
+	ManifestAddOptions
+	ManifestRemoveOptions
+}
+
+// ManifestRemoveOptions provides the model for removing digests from a manifest
+//
+// swagger:model
+type ManifestRemoveOptions struct {
+}
+
+// ManifestModifyReport provides the model for removed digests and changed manifest
+//
+// swagger:model
+type ManifestModifyReport struct {
+	// Manifest List ID
+	ID string `json:"Id"`
+	// Images to removed from manifest list, otherwise not provided.
+	Images []string `json:"images,omitempty" schema:"images"`
+	// Errors associated with operation
+	Errors []error `json:"errors,omitempty"`
 }