Editing SimTX API/Extension catalog protocol

{{SimTX API navigation}}
The '''extension catalog''' is the server's shared library of [[Lua extensions]] and station presets. It is accessed with four requests of the [[SimTX API/Control session|control session]], documented here. Users' view of the catalog is described in [[Extension catalog]]; the package format is in [[Lua extension manifest]].

== Requests ==
{| class="wikitable"
! Request !! Response !! Permission
|-
| [[SimTX API/Packets/CatalogListRequest|CatalogListRequest]] (36) || [[SimTX API/Packets/CatalogList|CatalogList]] (36) || None
|-
| [[SimTX API/Packets/CatalogFetch|CatalogFetch]] (37) || [[SimTX API/Packets/CatalogEntry|CatalogEntry]] (37) || None
|-
| [[SimTX API/Packets/CatalogUpload|CatalogUpload]] (38) || [[SimTX API/Packets/CatalogUploadResult|CatalogUploadResult]] (38) || <code>catalog.publish</code>
|-
| [[SimTX API/Packets/CatalogDelete|CatalogDelete]] (39) || [[SimTX API/Packets/CatalogDeleteResult|CatalogDeleteResult]] (39) || <code>catalog.publish</code>, owner only
|}

The numbers are the frame member numbers. All four count as heavy requests for [[SimTX API/Control session#Rate limits|rate limiting]]. Each carries a <code>request_id</code> that its response echoes. A refused request is answered with [[SimTX API/Packets/Error|Error]] carrying that <code>request_id</code> and a message that says what to fix; the session continues.

Browsing works anonymously. Publishing requires an authenticated control session: obtain a [[SimTX API/Game tickets|game ticket]] with role <code>control</code> (which itself requires <code>catalog.publish</code>) and present it in the hello.

== Entries ==
A catalog entry has a numeric ID, a '''kind''', a name, an author, a revision number and a set of text files.

{| class="wikitable"
! Kind !! Content
|-
| <code>extension</code> || A Lua extension package: an <code>extension.properties</code> manifest and one or more <code>.lua</code> files.
|-
| <code>preset</code> || A station preset: exactly one <code>.stxpreset</code> file.
|}

Extensions also report their package ID, version, dependencies and [[SimTX API/Data types#Catalog type|types]], read from the manifest at upload time.

=== Ownership and revisions ===
Entry names are unique on a server, compared without regard to case. The account that first publishes a name owns it.
* When the owner uploads an entry with the same name again, the existing entry is replaced: it keeps its ID, its files are replaced, and its revision increases by one. The [[SimTX API/Packets/CatalogUploadResult|CatalogUploadResult]] has <code>updated = true</code>.
* When another account uploads that name, the upload fails with [[SimTX API/Packets/Error|Error]] <code>FORBIDDEN</code>: ''An item named 'X' already exists (by Author)''.
* An extension's package ID must also be unique across the catalog and cannot change between revisions.
* Only the owner can delete an entry. There is no protocol-level override.

== Typical flows ==
'''Browsing'''
# Send CatalogListRequest. Show the entries from CatalogList.
# When the user opens one, send CatalogFetch with its ID and read the files from CatalogEntry. An entry removed in the meantime is answered with Error <code>NOT_FOUND</code>.
# Cache files by entry ID and revision; a changed revision in the list means the entry was updated.

'''Publishing'''
# Collect the files. For an extension, include <code>extension.properties</code> and every <code>.lua</code> file the manifest refers to.
# Send CatalogUpload. On success, CatalogUploadResult carries the entry ID.
# On failure, show the Error's message to the user. It names the rule that was broken.

== Upload rules ==
The server validates every upload and reports the first problem found in an [[SimTX API/Packets/Error|Error]].

{| class="wikitable"
! Rule !! Limit
|-
| Kind || <code>extension</code> or <code>preset</code>
|-
| Name || 1 to 64 characters after trimming; unique per server
|-
| Description || At most 500 characters
|-
| Categories || At most 12; each 1 to 32 characters, no commas or control characters; duplicates ignored without regard to case. Categories are free text.
|-
| Files || 1 to 64 (a preset: exactly 1)
|-
| File path || At most 128 characters, relative, <code>/</code> separators only, no empty, <code>.</code> or <code>..</code> segments, unique without regard to case
|-
| File names || Extension: <code>extension.properties</code> or <code>*.lua</code>. Preset: <code>*.stxpreset</code>.
|-
| File content || Not blank; at most 60,000 bytes of UTF-8 per file
|-
| Manifest || Must be valid. See [[Lua extension manifest]]. Manifest errors are reported verbatim.
|-
| Quotas || 32 entries and 64 MiB per author; 512 MiB per server. These are server defaults and may differ.
|}

{| class="wikitable"
! Error code !! Typical messages
|-
| <code>FORBIDDEN</code> || ''Publishing requires catalog.publish'', ''An item named 'X' already exists (by Author)'', ''Only Author can remove this publication''
|-
| <code>INVALID_REQUEST</code> || ''Unknown catalog item kind 'X''', ''A preset is exactly one .stxpreset file'', ''Bad file path 'X''', manifest errors
|-
| <code>NOT_FOUND</code> || ''That item is no longer in the catalog''
|-
| <code>LIMIT_REACHED</code> || ''Catalog entry quota reached (32)'', ''Catalog storage quota reached'', ''Server catalog storage is full''
|-
| <code>UNAVAILABLE</code> || ''This server has no catalog'', ''The catalog is temporarily unavailable''
|-
| <code>INTERNAL</code> || ''Could not store the item''
|}

{{SimTX API navbox}}
[[Category:SimTX API]]
[[Category:SimTX API sessions]]