feat(packages): expose package file properties in the package files API (#40066)

Package files carry type specific properties like `debian.distribution`,
`debian.component`, `rpm.group` or `alpine.branch` that decide where a
file lives in a registry, but the API never returned them. A client
listing `GET /packages/{owner}/{type}/{name}/{version}/files` could not
tell which distribution or component a file belongs to, or tell apart
same-named files in different ones. Tools copying packages between
instances, like https://gitea.com/gitea/importer, need them to re-upload
a file to the same place.

This adds a `properties` map to `PackageFile`, limited to the properties
that locate a file. Internal ones like the rpm, alpine, arch and conda
metadata or the Debian control file stay hidden, as they can be many MiB
per file.

Co-authored-by: silverwind <me@silverwind.io>
Co-authored-by: wxiaoguang <wxiaoguang@gmail.com>

services/convert/package.go

@@ -5,11 +5,13 @@ package convert
 
 import (
 	"context"
+	"slices"
 
 	"gitea.dev/models/packages"
 	access_model "gitea.dev/models/perm/access"
 	user_model "gitea.dev/models/user"
 	api "gitea.dev/modules/structs"
+	packages_service "gitea.dev/services/packages"
 )
 
 // ToPackage convert a packages.PackageDescriptor to api.Package
@@ -40,7 +42,14 @@ func ToPackage(ctx context.Context, pd *packages.PackageDescriptor, doer *user_m
 }
 
 // ToPackageFile converts packages.PackageFileDescriptor to api.PackageFile
-func ToPackageFile(pfd *packages.PackageFileDescriptor) *api.PackageFile {
+func ToPackageFile(packageType packages.Type, pfd *packages.PackageFileDescriptor) *api.PackageFile {
+	properties := make(map[string]string)
+	publicPropertyNames := packages_service.GetSpecManager().Get(packageType).PublicPropertyNames()
+	for _, pp := range pfd.Properties {
+		if slices.Contains(publicPropertyNames, pp.Name) {
+			properties[pp.Name] = pp.Value
+		}
+	}
 	return &api.PackageFile{
 		ID:         pfd.File.ID,
 		Size:       pfd.Blob.Size,
@@ -49,5 +58,6 @@ func ToPackageFile(pfd *packages.PackageFileDescriptor) *api.PackageFile {
 		HashSHA1:   pfd.Blob.HashSHA1,
 		HashSHA256: pfd.Blob.HashSHA256,
 		HashSHA512: pfd.Blob.HashSHA512,
+		Properties: properties,
 	}
 }

services/packages/alpine/spec.go

@@ -0,0 +1,22 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package alpine
+
+import (
+	alpine_module "gitea.dev/modules/packages/alpine"
+	packages_service "gitea.dev/services/packages"
+)
+
+type Specialization struct {
+	packages_service.SpecGetViewPackageVersionData
+	packages_service.SpecOnBeforeRemovePackageAll
+	packages_service.SpecOnBeforeRemovePackageVersion
+	packages_service.SpecRenderUsageManual
+}
+
+var _ packages_service.Specialization = (*Specialization)(nil)
+
+func (s Specialization) PublicPropertyNames() []string {
+	return []string{alpine_module.PropertyBranch, alpine_module.PropertyRepository, alpine_module.PropertyArchitecture}
+}

services/packages/arch/spec.go

@@ -0,0 +1,22 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package arch
+
+import (
+	arch_module "gitea.dev/modules/packages/arch"
+	packages_service "gitea.dev/services/packages"
+)
+
+type Specialization struct {
+	packages_service.SpecGetViewPackageVersionData
+	packages_service.SpecOnBeforeRemovePackageAll
+	packages_service.SpecOnBeforeRemovePackageVersion
+	packages_service.SpecRenderUsageManual
+}
+
+var _ packages_service.Specialization = (*Specialization)(nil)
+
+func (s Specialization) PublicPropertyNames() []string {
+	return []string{arch_module.PropertyRepository, arch_module.PropertyArchitecture}
+}

services/packages/conan/spec.go

@@ -0,0 +1,22 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package conan
+
+import (
+	conan_module "gitea.dev/modules/packages/conan"
+	packages_service "gitea.dev/services/packages"
+)
+
+type Specialization struct {
+	packages_service.SpecGetViewPackageVersionData
+	packages_service.SpecOnBeforeRemovePackageAll
+	packages_service.SpecOnBeforeRemovePackageVersion
+	packages_service.SpecRenderUsageManual
+}
+
+var _ packages_service.Specialization = (*Specialization)(nil)
+
+func (s Specialization) PublicPropertyNames() []string {
+	return []string{conan_module.PropertyRecipeUser, conan_module.PropertyRecipeChannel, conan_module.PropertyRecipeRevision, conan_module.PropertyPackageReference, conan_module.PropertyPackageRevision}
+}

services/packages/conda/spec.go

@@ -0,0 +1,22 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package conda
+
+import (
+	conda_module "gitea.dev/modules/packages/conda"
+	packages_service "gitea.dev/services/packages"
+)
+
+type Specialization struct {
+	packages_service.SpecGetViewPackageVersionData
+	packages_service.SpecOnBeforeRemovePackageAll
+	packages_service.SpecOnBeforeRemovePackageVersion
+	packages_service.SpecRenderUsageManual
+}
+
+var _ packages_service.Specialization = (*Specialization)(nil)
+
+func (s Specialization) PublicPropertyNames() []string {
+	return []string{conda_module.PropertySubdir}
+}

services/packages/debian/spec.go

@@ -85,3 +85,7 @@ func (s Specialization) RenderSetupManual(ctx context.Context, pkg *packages_mod
 	w.WriteHTML(`</div>`)
 	return w.HTMLString()
 }
+
+func (s Specialization) PublicPropertyNames() []string {
+	return []string{debian_module.PropertyDistribution, debian_module.PropertyComponent, debian_module.PropertyArchitecture}
+}

services/packages/nuget/spec.go

@@ -0,0 +1,22 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package nuget
+
+import (
+	nuget_module "gitea.dev/modules/packages/nuget"
+	packages_service "gitea.dev/services/packages"
+)
+
+type Specialization struct {
+	packages_service.SpecGetViewPackageVersionData
+	packages_service.SpecOnBeforeRemovePackageAll
+	packages_service.SpecOnBeforeRemovePackageVersion
+	packages_service.SpecRenderUsageManual
+}
+
+var _ packages_service.Specialization = (*Specialization)(nil)
+
+func (s Specialization) PublicPropertyNames() []string {
+	return []string{nuget_module.PropertySymbolID}
+}

services/packages/packages.go

@@ -35,6 +35,7 @@ var (
 )
 
 type Specialization interface {
+	PublicPropertyNames() []string // only properties locating the file, the others are internal and can be large
 	OnBeforeRemovePackageAll(ctx context.Context, doer *user_model.User, pkg *packages_model.Package, pds []*packages_model.PackageDescriptor) error
 	OnBeforeRemovePackageVersion(ctx context.Context, doer *user_model.User, pd *packages_model.PackageDescriptor) error
 	GetViewPackageVersionData(ctx context.Context, pd *packages_model.PackageDescriptor) (any, error)

services/packages/pkgspec/manager.go

@@ -6,14 +6,28 @@ package pkgspec
 import (
 	packages_model "gitea.dev/models/packages"
 	packages_service "gitea.dev/services/packages"
+	"gitea.dev/services/packages/alpine"
+	"gitea.dev/services/packages/arch"
+	"gitea.dev/services/packages/conan"
+	"gitea.dev/services/packages/conda"
 	"gitea.dev/services/packages/debian"
+	"gitea.dev/services/packages/nuget"
+	"gitea.dev/services/packages/rpm"
 	"gitea.dev/services/packages/terraform"
+	"gitea.dev/services/packages/vagrant"
 )
 
 func InitManager() error {
 	mgr := packages_service.GetSpecManager()
+	mgr.Add(packages_model.TypeAlpine, &alpine.Specialization{})
+	mgr.Add(packages_model.TypeArch, &arch.Specialization{})
+	mgr.Add(packages_model.TypeConan, &conan.Specialization{})
+	mgr.Add(packages_model.TypeConda, &conda.Specialization{})
 	mgr.Add(packages_model.TypeDebian, &debian.Specialization{})
+	mgr.Add(packages_model.TypeNuGet, &nuget.Specialization{})
+	mgr.Add(packages_model.TypeRpm, &rpm.Specialization{})
 	mgr.Add(packages_model.TypeTerraformState, &terraform.Specialization{})
+	mgr.Add(packages_model.TypeVagrant, &vagrant.Specialization{})
 	// TODO: add more in the future, refactor the existing code to use this approach
 	return nil
 }

services/packages/rpm/spec.go

@@ -0,0 +1,22 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package rpm
+
+import (
+	rpm_module "gitea.dev/modules/packages/rpm"
+	packages_service "gitea.dev/services/packages"
+)
+
+type Specialization struct {
+	packages_service.SpecGetViewPackageVersionData
+	packages_service.SpecOnBeforeRemovePackageAll
+	packages_service.SpecOnBeforeRemovePackageVersion
+	packages_service.SpecRenderUsageManual
+}
+
+var _ packages_service.Specialization = (*Specialization)(nil)
+
+func (s Specialization) PublicPropertyNames() []string {
+	return []string{rpm_module.PropertyGroup, rpm_module.PropertyArchitecture}
+}

services/packages/spec.go

@@ -36,7 +36,14 @@ func (*SpecRenderUsageManual) RenderSetupManual(ctx context.Context, pkg *packag
 	return ""
 }
 
+type SpecPublicPropertyNames struct{}
+
+func (*SpecPublicPropertyNames) PublicPropertyNames() []string {
+	return nil
+}
+
 type specDefault struct {
+	SpecPublicPropertyNames
 	SpecGetViewPackageVersionData
 	SpecOnBeforeRemovePackageAll
 	SpecOnBeforeRemovePackageVersion

services/packages/terraform/spec.go

@@ -15,6 +15,7 @@ import (
 )
 
 type Specialization struct {
+	packages_service.SpecPublicPropertyNames
 	packages_service.SpecRenderUsageManual
 }
 

services/packages/vagrant/spec.go

@@ -0,0 +1,22 @@
+// Copyright 2026 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package vagrant
+
+import (
+	vagrant_module "gitea.dev/modules/packages/vagrant"
+	packages_service "gitea.dev/services/packages"
+)
+
+type Specialization struct {
+	packages_service.SpecGetViewPackageVersionData
+	packages_service.SpecOnBeforeRemovePackageAll
+	packages_service.SpecOnBeforeRemovePackageVersion
+	packages_service.SpecRenderUsageManual
+}
+
+var _ packages_service.Specialization = (*Specialization)(nil)
+
+func (s Specialization) PublicPropertyNames() []string {
+	return []string{vagrant_module.PropertyProvider}
+}