From a0a425a13ba587829a831aaecd8469d39d372111 Mon Sep 17 00:00:00 2001 From: zeripath Date: Sat, 12 Nov 2022 18:59:15 +0000 Subject: [PATCH] Add some documentation to packages (#21648) In #21637 it was mentioned that the purpose of the API routes for the packages is unclear. This PR adds some documentation. Fix #21637 Signed-off-by: Andrew Thornton Co-authored-by: KN4CK3R --- routers/api/packages/api.go | 7 ++++++- routers/api/v1/api.go | 1 + routers/init.go | 8 +++++++- 3 files changed, 14 insertions(+), 2 deletions(-) diff --git a/routers/api/packages/api.go b/routers/api/packages/api.go index 6f53bc4ae..11e7e5d6a 100644 --- a/routers/api/packages/api.go +++ b/routers/api/packages/api.go @@ -40,7 +40,9 @@ func reqPackageAccess(accessMode perm.AccessMode) func(ctx *context.Context) { } } -func Routes(ctx gocontext.Context) *web.Route { +// CommonRoutes provide endpoints for most package managers (except containers - see below) +// These are mounted on `/api/packages` (not `/api/v1/packages`) +func CommonRoutes(ctx gocontext.Context) *web.Route { r := web.NewRoute() r.Use(context.PackageContexter(ctx)) @@ -301,6 +303,9 @@ func Routes(ctx gocontext.Context) *web.Route { return r } +// ContainerRoutes provides endpoints that implement the OCI API to serve containers +// These have to be mounted on `/v2/...` to comply with the OCI spec: +// https://github.com/opencontainers/distribution-spec/blob/main/spec.md func ContainerRoutes(ctx gocontext.Context) *web.Route { r := web.NewRoute() diff --git a/routers/api/v1/api.go b/routers/api/v1/api.go index ee1804daa..e41fccb63 100644 --- a/routers/api/v1/api.go +++ b/routers/api/v1/api.go @@ -1073,6 +1073,7 @@ func Routes(ctx gocontext.Context) *web.Route { }, repoAssignment()) }) + // NOTE: these are Gitea package management API - see packages.CommonRoutes and packages.DockerContainerRoutes for endpoints that implement package manager APIs m.Group("/packages/{username}", func() { m.Group("/{type}/{name}/{version}", func() { m.Get("", packages.GetPackage) diff --git a/routers/init.go b/routers/init.go index 53b33f468..fecc5c439 100644 --- a/routers/init.go +++ b/routers/init.go @@ -185,8 +185,14 @@ func NormalRoutes(ctx context.Context) *web.Route { r.Mount("/", web_routers.Routes(ctx)) r.Mount("/api/v1", apiv1.Routes(ctx)) r.Mount("/api/internal", private.Routes()) + if setting.Packages.Enabled { - r.Mount("/api/packages", packages_router.Routes(ctx)) + // Add endpoints to match common package manager APIs + + // This implements package support for most package managers + r.Mount("/api/packages", packages_router.CommonRoutes(ctx)) + + // This implements the OCI API (Note this is not preceded by /api but is instead /v2) r.Mount("/v2", packages_router.ContainerRoutes(ctx)) } return r