From 01b059bf5d326c953768c45fe2ef3d80e7e55540 Mon Sep 17 00:00:00 2001 From: Till Wegmueller Date: Wed, 23 Jul 2025 22:09:09 +0200 Subject: [PATCH] Expand pkg5 documentation with additional details on repository operations, including administrative tasks, enhanced metadata handling, new operation versions, and improved search functionality. --- doc/pkg5_docs/depot.txt | 359 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 355 insertions(+), 4 deletions(-) diff --git a/doc/pkg5_docs/depot.txt b/doc/pkg5_docs/depot.txt index 03dfdb6..74555e2 100644 --- a/doc/pkg5_docs/depot.txt +++ b/doc/pkg5_docs/depot.txt @@ -162,6 +162,10 @@ DEPOT These operations alter a repository's catalog, package metadata, and allow storage of package content. + - administrative + These operations perform administrative tasks on the repository or + depot server. + 2.2.2. Modes Which types of operations are available is dependent on which mode the depot @@ -202,7 +206,48 @@ DEPOT The contents of the file, compressed using the gzip compression algorithm. -2.2.2. Depot Operations + Version 1: + A GET or POST/PUT operation that retrieves or uploads the contents of a file. + For GET requests, it behaves the same as Version 0. + For POST/PUT requests, it allows uploading file content to the repository. + + Example: + URL: + http://pkg.opensolaris.org/release/file/1/ + a00030db8b91f85d0b7144d0d4ef241a3f1ae28f + + Expects: + For GET: A SHA-1 hash of the file's content belonging to a package in the + request path. + For POST/PUT: The file content in the request body. + + Returns: + For GET: The contents of the file, compressed using the gzip compression + algorithm. + For POST/PUT: Response status of 200 on success; any other status indicates + failure. + + Version 2: + Extends Version 1 to add support for HEAD requests. For GET and POST/PUT + requests, it behaves the same as Version 1. For HEAD requests, it returns + metadata about the file without returning the file content. + + Example: + URL: + http://pkg.opensolaris.org/release/file/2/ + a00030db8b91f85d0b7144d0d4ef241a3f1ae28f + + Expects: + For GET/POST/PUT: Same as Version 1. + For HEAD: A SHA-1 hash of the file's content belonging to a package in the + request path. + + Returns: + For GET/POST/PUT: Same as Version 1. + For HEAD: Response headers containing file metadata including compressed + attributes in X-Ipkg-Attr-{n} headers. + +2.2.4. Depot Operations - versions Version 0: @@ -235,7 +280,23 @@ DEPOT close 0 open 0 -2.2.2. Meta-data Operations + - status + Version 0: + A GET operation that retrieves a JSON formatted dictionary containing + statistics information for the repository being served. + + Example: + URL: + http://pkg.opensolaris.org/status/0/ + + Expects: + Nothing + + Returns: + A JSON formatted dictionary containing statistics information for + the repository being served. + +2.2.5. Meta-data Operations - catalog Version 0: @@ -256,6 +317,164 @@ DEPOT that were added since the specified date as they are found in the catalog file, separated by newlines. + Version 1: + A GET operation that retrieves the contents of a specific catalog file + by name. + + Example: + URL: + http://pkg.opensolaris.org/catalog/1/catalog.attrs + + Expects: + A catalog file name in the request path. + + Returns: + The contents of the specified catalog file. + + Valid Catalog File Names: + The following catalog files are valid for the V1 catalog endpoint: + + catalog.attrs + Contains metadata about the catalog, including creation date, + last modified date, package counts, and information about + available catalog parts. + + Sample Output: + { + "_SIGNATURE": { + "sha-1": "8f5c22fd8218f7a0982d3e3fdd01e40671cb9cab" + }, + "created": "20050614T080000.234231Z", + "last-modified": "20090508T161025.686485Z", + "package-count": 40802, + "package-version-count": 1706, + "parts": { + "catalog.base.C": { + "last-modified": "20090508T161025.686485Z", + "signature-sha-1": "9b37ef267ae6aa8a31b878aad4e9baa234470d45" + }, + "catalog.dependency.C": { + "last-modified": "20090508T161025.686485Z", + "signature-sha-1": "0c896321c59fd2cd4344fec074d55ba9c88f75e8" + }, + "catalog.summary.C": { + "last-modified": "20090508T161025.686485Z", + "signature-sha-1": "b3a6ab53677c7b5f94c9bd551a484d57b54ed6f7" + } + }, + "version": 1 + } + + catalog.base.C + Contains the FMRIs of packages in the repository and optional + digest values for verifying manifest contents. + + Sample Output: + { + "_SIGNATURE": { + "sha-1": "9b37ef267ae6aa8a31b878aad4e9baa234470d45" + }, + "opensolaris.org": { + "SUNWipkg": [ + { + "version": "0.5.11,5.11-0.117:20090623T135937Z", + "signature-sha-1": "596f26c4fc725b486faba089071d2b3b35482114" + }, + { + "version": "0.5.11,5.11-0.118:20090707T220625Z", + "signature-sha-1": "ab6f26c4fc725b386faca089071d2b3d35482114" + } + ] + } + } + + catalog.dependency.C + Contains package FMRIs, depend actions, and set actions for + facets or variants. + + Sample Output: + { + "_SIGNATURE": { + "sha-1": "0c896321c59fd2cd4344fec074d55ba9c88f75e8" + }, + "opensolaris.org": { + "SUNWdvdrw": [ + { + "version": "5.21.4.10.8,5.11-0.108:20090218T042840Z", + "actions": [ + "set name=variant.zone value=global value=nonglobal", + "set name=variant.arch value=sparc value=i386", + "depend fmri=SUNWlibms@0.5.11-0.108 type=require", + "depend fmri=SUNWlibC@0.5.11-0.108 type=require", + "depend fmri=SUNWcsl@0.5.11-0.108 type=require" + ] + } + ] + } + } + + catalog.summary.C + Contains package FMRIs and set actions (excluding those for + facets or variants). + + Sample Output: + { + "_SIGNATURE": { + "catalog-sha-1": "b3a6ab53677c7b5f94c9bd551a484d57b54ed6f7" + }, + "opensolaris.org": { + "SUNWdvdrw": [ + { + "version": "5.21.4.10.8,5.11-0.108:20090218T042840Z", + "actions": [ + "set name=description value=\"DVD creation utilities\"", + "set name=info.classification value=org.opensolaris.category.2008:System/Media" + ] + } + ] + } + } + + catalog.summary. + Locale-specific versions of the summary catalog, where + is an OpenSolaris system locale name. + + update.. + Update logs containing incremental changes to the catalog, + where is a UTC date and time in ISO-8601 'reduced + accuracy basic format' and is an OpenSolaris + system locale name. + + Sample Output: + { + "_SIGNATURE": { + "sha-1": "0c896321c59fd2cd4344fec074d55ba9c88f75e8" + }, + "opensolaris.org": { + "SUNWdvdrw": [ + { + "op-type": "add", + "op-time": "20090524T042841Z", + "version": "5.21.4.10.8,5.11-0.111:20090524T042840Z", + "catalog.dependency.C": { + "actions": [ + "depend fmri=SUNWlibms@0.5.11-0.111 type=require", + "depend fmri=SUNWlibC@0.5.11-0.111 type=require", + "depend fmri=SUNWcsl@0.5.11-0.111 type=require" + ] + }, + "catalog.summary.C": { + "actions": [ + "set name=description value=\"DVD creation utilities\"", + "set name=info.classification value=org.opensolaris.category.2008:System/Media" + ] + }, + "signature-sha-1": "fe6f26c4fc124b386faca089071d2b3a35482114" + } + ] + } + } + - info Version 0: A GET operation that retrieves a text/plain description of a @@ -305,6 +524,25 @@ DEPOT Returns: The contents of the package's manifest file. + Version 1: + A GET or POST/PUT operation that retrieves or uploads the contents of a + manifest file. For GET requests, it behaves the same as Version 0. + For POST/PUT requests, it allows uploading manifest content to the repository. + + Example: + URL: + http://pkg.opensolaris.org/manifest/1/entire@0.5.11,5.11-0.101:20081119T235706Z + + Expects: + For GET: A URL-encoded pkg(5) FMRI excluding the 'pkg:/' scheme prefix + and publisher information and including the full version information. + For POST/PUT: The manifest content in the request body. + + Returns: + For GET: The contents of the package's manifest file. + For POST/PUT: Response status of 200 on success; any other status indicates + failure. + - p5i Version 0: A GET operation that retrieves an application/vnd.pkg5.info @@ -351,6 +589,24 @@ DEPOT configuration's publisher information. The Content-Type of the response is 'application/vnd.pkg5.info'. + Version 1: + A GET operation that retrieves an application/vnd.pkg5.info + datastream representing publisher information for a specific publisher + or all publishers. This version provides improved error handling and + response formatting. + + Example: + URL: + http://pkg.opensolaris.org/release/publisher/1 + + Expects: + Nothing + + Returns: + Returns a pkg(5) information datastream based on the repository + configuration's publisher information. The Content-Type of the + response is 'application/vnd.pkg5.info'. + - search Version 0: A GET operation that retrieves a text/plain list of packages with @@ -381,7 +637,54 @@ DEPOT basename pkg:/SUNWvim@7.1.284,5.11-0.101:20081119T230659Z dir usr/share/vim basename pkg:/SUNWvim@7.1.284,5.11-0.93:20080708T171331Z file usr/bin/vim -2.2.3. Publishing Operations + Version 1: + A GET or POST operation that retrieves a text/plain list of packages with + metadata that matches the specified criteria. This version adds support for + POST requests, case-sensitive searches, and returns a validation string + to confirm the client is talking to a valid search server. + + Example: + URL: + http://pkg.opensolaris.org/release/search/1/vim + + Expects: + For GET: A URL-encoded token representing the search criteria. + For POST: Search criteria in the request parameters. + + Returns: + A text/plain list of matching entries, preceded by a validation string. + Each entry consists of a set of space-separated values: + + query_number - which query in the request this result is for + + return_type - whether the result is an action or package + + fmri - the fmri of the package that contains the match + + field - the field that matched (URL-encoded) + + line - the line that matched (for actions) + + If no results are found, a 204 No Content status is returned. + + - index + Version 0: + A GET operation that provides an administrative interface for search + indexing. Returns no output if successful; otherwise the response body + will contain the failure details. + + Example: + URL: + http://pkg.opensolaris.org/release/index/0/refresh + + Expects: + A command to execute, such as "refresh" to update search indexes. + + Returns: + No output if successful; otherwise the response body will contain + the failure details. + +2.2.6. Publishing Operations - add Version 0: @@ -429,6 +732,23 @@ DEPOT Response status of 200 on success; any other status indicates failure. + - append + Version 0: + A POST operation that starts an append transaction for the package + name specified in the request path. Returns no output. + + Example: + URL: + http://pkg.opensolaris.org/append/0/system%2Flibc@0.1-98 + + Expects: + A URL-encoded pkg(5) FMRI (excluding timestamp). + + Returns: + Response status of 200 on success and an identifier for the new + transaction in the 'Transaction-ID' response header; any other + status indicates failure. + - close Version 0: A GET operation that ends an in-flight transaction for the @@ -464,5 +784,36 @@ DEPOT transaction in the 'Transaction-ID' response header; any other status indicates failure. -3. References +2.2.7. Administrative Operations + - admin + Version 0: + A GET operation that executes a specified repository administration + operation based on the provided query string. + + Example: + URL: + http://pkg.opensolaris.org/release/admin/0?cmd=refresh-index + + Expects: + A command parameter in the query string. Available commands are: + rebuild + Discard search data and package catalogs and rebuild both. + rebuild-indexes + Discard search data and rebuild. + rebuild-packages + Discard package catalogs and rebuild. + refresh + Update search and package data. + refresh-indexes + Update search data. (Add packages found in the repository + to their related search indexes.) + refresh-packages + Update package data. (Add packages found in the repository + to their related catalog.) + + Returns: + No output if successful; otherwise the response body will contain + the failure details. + +3. References \ No newline at end of file