Merge pull request #369 from yue9944882/feat/support-short-name

Feat: Support short name provider

cmd/apiregister-gen/generators/parser.go

@@ -112,6 +112,8 @@ type APIResource struct {
 	Kind string
 	// Resource is the resource name - e.g. peachescastles
 	Resource string
+	// ShortName is the resource short name - e.g. pc
+	ShortName string
 	// REST is the rest.Storage implementation used to handle requests
 	// This field is optional. The standard REST implementation will be used
 	// by default.
@@ -225,6 +227,7 @@ func (b *APIsBuilder) ParseAPIs() {
 					StatusStrategy: resource.StatusStrategy,
 					Strategy:       resource.Strategy,
 					NonNamespaced:  resource.NonNamespaced,
+					ShortName:      resource.ShortName,
 				}
 				apiVersion.Resources[kind] = apiResource
 				// Set the package for the api version
@@ -283,6 +286,7 @@ func (b *APIsBuilder) ParseIndex() {
 
 		r.Resource = rt.Resource
 		r.REST = rt.REST
+		r.ShortName = rt.ShortName
 
 		r.Strategy = rt.Strategy
 
@@ -375,9 +379,10 @@ func (b *APIsBuilder) GetNameAndImport(tags SubresourceTags) (string, string) {
 
 // ResourceTags contains the tags present in a "+resource=" comment
 type ResourceTags struct {
-	Resource string
-	REST     string
-	Strategy string
+	Resource  string
+	REST      string
+	Strategy  string
+	ShortName string
 }
 
 // ParseResourceTag parses the tags in a "+resource=" comment into a ResourceTags struct
@@ -398,6 +403,8 @@ func ParseResourceTag(tag string) ResourceTags {
 			result.Resource = value
 		case "strategy":
 			result.Strategy = value
+		case "shortname":
+			result.ShortName = value
 		}
 	}
 	return result

cmd/apiregister-gen/generators/unversioned_generator.go

@@ -72,11 +72,19 @@ func (d *unversionedGenerator) Finalize(context *generator.Context, w io.Writer)
 var UnversionedAPITemplate = `
 var (
 	{{ range $api := .UnversionedResources -}}
+	{{- if $api.ShortName -}}
+	Internal{{ $api.Kind }} = builders.NewInternalResourceWithShortcuts(
+	{{ else -}}
 	Internal{{ $api.Kind }} = builders.NewInternalResource(
+	{{ end -}}
 		"{{ $api.Resource }}",
         "{{ $api.Kind }}",
 		func() runtime.Object { return &{{ $api.Kind }}{} },
 		func() runtime.Object { return &{{ $api.Kind }}List{} },
+	{{ if $api.ShortName -}}
+		[]string{"{{ $api.ShortName }}"},
+		[]string{"aggregation"}, // TBD
+	{{ end -}}
 	)
 	Internal{{ $api.Kind }}Status = builders.NewInternalResourceStatus(
 		"{{ $api.Resource }}",

example/pkg/apis/kingsport/v1/festival_types.go

@@ -27,7 +27,7 @@ import (
 
 // Festival
 // +k8s:openapi-gen=true
-// +resource:path=festivals,strategy=FestivalStrategy
+// +resource:path=festivals,strategy=FestivalStrategy,shortname=fs
 type Festival struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`

pkg/builders/api_unversioned_resource_builder.go

@@ -28,6 +28,16 @@ func NewInternalResource(name, kind string, new, newList func() runtime.Object)
 	return NewBuilder(name, kind, "", new, newList, true)
 }
 
+// NewInternalResourceWithShortcuts creates a new strategy for a resource with shortnames and categories
+// name - name of the resource - e.g. "deployments"
+// new - function for creating new empty UNVERSIONED instances - e.g. func() runtime.Object { return &Deployment{} }
+// newList - function for creating an empty list of UNVERSIONED instances - e.g. func() runtime.Object { return &DeploymentList{} }
+// shortnames - shortnames of the resource - e.g. "deploy"
+// categories - categories of the resource - e.g. "aggregation"
+func NewInternalResourceWithShortcuts(name, kind string, new, newList func() runtime.Object, shortnames, categories []string) UnversionedResourceBuilder {
+	return NewBuilderWithShortcuts(name, kind, "", new, newList, true, shortnames, categories)
+}
+
 // NewInternalResourceStatus returns a new strategy for the status subresource of an object
 // name - name of the resource - e.g. "deployments"
 // new - function for creating new empty UNVERSIONED instances - e.g. func() runtime.Object { return &Deployment{} }
@@ -62,12 +72,30 @@ func NewBuilder(
 	useRegistryStore bool) UnversionedResourceBuilder {
 
 	return &UnversionedResourceBuilderImpl{
-		path,
-		name,
-		kind,
-		new,
-		newList,
-		useRegistryStore,
+		Path:             path,
+		Name:             name,
+		Kind:             kind,
+		NewFunc:          new,
+		NewListFunc:      newList,
+		UseRegistryStore: useRegistryStore,
+	}
+}
+
+func NewBuilderWithShortcuts(
+	name, kind, path string,
+	new, newList func() runtime.Object,
+	useRegistryStore bool,
+	shortnames, categories []string) UnversionedResourceBuilder {
+
+	return &UnversionedResourceBuilderImpl{
+		Path:             path,
+		Name:             name,
+		Kind:             kind,
+		NewFunc:          new,
+		NewListFunc:      newList,
+		UseRegistryStore: useRegistryStore,
+		ShortNames:       shortnames,
+		Categories:       categories,
 	}
 }
 
@@ -77,6 +105,8 @@ type WithList interface {
 
 type UnversionedResourceBuilder interface {
 	WithList
+	WithShortNames
+	WithCategories
 	New() runtime.Object
 
 	GetPath() string
@@ -92,6 +122,9 @@ type UnversionedResourceBuilderImpl struct {
 	NewFunc          func() runtime.Object
 	NewListFunc      func() runtime.Object
 	UseRegistryStore bool
+
+	ShortNames []string
+	Categories []string
 }
 
 func (b *UnversionedResourceBuilderImpl) GetPath() string {
@@ -123,3 +156,25 @@ func (b *UnversionedResourceBuilderImpl) NewList() runtime.Object {
 	}
 	return b.NewListFunc()
 }
+
+var _ WithShortNames = &UnversionedResourceBuilderImpl{}
+
+func (b *UnversionedResourceBuilderImpl) GetShortNames() []string {
+	return b.ShortNames
+}
+
+var _ WithCategories = &UnversionedResourceBuilderImpl{}
+
+func (b *UnversionedResourceBuilderImpl) GetCategories() []string {
+	return b.Categories
+}
+
+type WithShortNames interface {
+	//AddShortName(shortName string)
+	GetShortNames() []string
+}
+
+type WithCategories interface {
+	//AddCategory(category string)
+	GetCategories() []string
+}

pkg/builders/api_versioned_resource_builder.go

@@ -123,25 +123,42 @@ func (b *versionedResourceBuilder) Build(
 	optionsGetter generic.RESTOptionsGetter) rest.StandardStorage {
 
 	// Set a default strategy
-	store := &StorageWrapper{registry.Store{
-		NewFunc:                  b.Unversioned.New,     // Use the unversioned type
-		NewListFunc:              b.Unversioned.NewList, // Use the unversioned type
-		DefaultQualifiedResource: b.getGroupResource(group),
-	}}
+	store := &StorageWrapper{
+		registry.Store{
+			NewFunc:                  b.Unversioned.New,     // Use the unversioned type
+			NewListFunc:              b.Unversioned.NewList, // Use the unversioned type
+			DefaultQualifiedResource: b.getGroupResource(group),
+		},
+	}
+	b.Storage = store
+
+	// the store-with-shortcuts will only be used if there're valid shortnames
+	storeWithShortcuts := &StorageWrapperWithShortcuts{
+		StorageWrapper: store,
+	}
+
+	wantsShortcuts := len(b.Unversioned.GetShortNames()) > 0
+	if wantsShortcuts {
+		// plants shortnames and an opt-out category into the storage
+		storeWithShortcuts.shortNames = b.Unversioned.GetShortNames()
+		storeWithShortcuts.categories = b.Unversioned.GetCategories()
+	}
 
 	// Use default, requires
 	options := &generic.StoreOptions{RESTOptions: optionsGetter}
 
 	if b.StorageBuilder != nil {
 		// Allow overriding the storage defaults
-		b.StorageBuilder.Build(b.StorageBuilder, store, options)
+		b.StorageBuilder.Build(b.StorageBuilder, storeWithShortcuts.StorageWrapper, options)
 	}
 
-	if err := store.CompleteWithOptions(options); err != nil {
+	if err := storeWithShortcuts.CompleteWithOptions(options); err != nil {
 		panic(err) // TODO: Propagate error up
 	}
-	b.Storage = store
-	return store
+	if wantsShortcuts {
+		b.Storage = storeWithShortcuts
+	}
+	return b.Storage
 }
 
 func (b *versionedResourceBuilder) GetStandardStorage() rest.StandardStorage {

pkg/builders/shortcut_storage_wrapper.go

@@ -0,0 +1,38 @@
+/*
+Copyright 2019 The Kubernetes Authors.
+
+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
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package builders
+
+import "k8s.io/apiserver/pkg/registry/rest"
+
+var _ rest.ShortNamesProvider = &StorageWrapperWithShortcuts{}
+var _ rest.CategoriesProvider = &StorageWrapperWithShortcuts{}
+
+type StorageWrapperWithShortcuts struct {
+	*StorageWrapper
+	shortNames []string
+	categories  []string
+}
+
+func (b *StorageWrapperWithShortcuts) ShortNames() []string {
+	// TODO(yue9944882): prevent shortname conflict or the client-side rest-mapping will crush
+	return b.shortNames
+}
+
+func (b *StorageWrapperWithShortcuts) Categories() []string {
+	// all the aggregated resource are considered in the "aggregation" category
+	return b.categories
+}