SimTX API v24/Extension catalog protocol: Difference between revisions
m Clanker moved page SimTX API/Extension catalog protocol to SimTX API v24/Extension catalog protocol: Archive the v24 protocol reference |
Archive the v24 protocol reference: use the v24 templates, links and categories |
||
| Line 1: | Line 1: | ||
{{SimTX API navigation}} | {{SimTX API v24 navigation}} | ||
The '''extension catalog''' is the server's shared library of [[Lua extensions]] and station presets. The official transmitter's catalog browser is built on 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]]. | The '''extension catalog''' is the server's shared library of [[Lua extensions]] and station presets. The official transmitter's catalog browser is built on four requests of the [[SimTX API v24/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 == | == Requests == | ||
| Line 6: | Line 6: | ||
! Request !! Response !! Permission | ! Request !! Response !! Permission | ||
|- | |- | ||
| [[SimTX API/Packets/CatalogListRequest|CatalogListRequest]] (20) || [[SimTX API/Packets/CatalogList|CatalogList]] (24) || None | | [[SimTX API v24/Packets/CatalogListRequest|CatalogListRequest]] (20) || [[SimTX API v24/Packets/CatalogList|CatalogList]] (24) || None | ||
|- | |- | ||
| [[SimTX API/Packets/CatalogFetch|CatalogFetch]] (21) || [[SimTX API/Packets/CatalogEntry|CatalogEntry]] (25) || None | | [[SimTX API v24/Packets/CatalogFetch|CatalogFetch]] (21) || [[SimTX API v24/Packets/CatalogEntry|CatalogEntry]] (25) || None | ||
|- | |- | ||
| [[SimTX API/Packets/CatalogUpload|CatalogUpload]] (22) || [[SimTX API/Packets/CatalogUploadResult|CatalogUploadResult]] (21) || <code>catalog.publish</code> | | [[SimTX API v24/Packets/CatalogUpload|CatalogUpload]] (22) || [[SimTX API v24/Packets/CatalogUploadResult|CatalogUploadResult]] (21) || <code>catalog.publish</code> | ||
|- | |- | ||
| [[SimTX API/Packets/CatalogDelete|CatalogDelete]] (26) || [[SimTX API/Packets/CatalogDeleteResult|CatalogDeleteResult]] (29) || <code>catalog.publish</code>, owner only | | [[SimTX API v24/Packets/CatalogDelete|CatalogDelete]] (26) || [[SimTX API v24/Packets/CatalogDeleteResult|CatalogDeleteResult]] (29) || <code>catalog.publish</code>, owner only | ||
|} | |} | ||
All four count as heavy requests for [[SimTX API/Control session#Rate limits|rate limiting]]. | All four count as heavy requests for [[SimTX API v24/Control session#Rate limits|rate limiting]]. | ||
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 handshake. | Browsing works anonymously. Publishing requires an authenticated control session: obtain a [[SimTX API v24/Game tickets|game ticket]] with role <code>control</code> (which itself requires <code>catalog.publish</code>) and present it in the handshake. | ||
== Entries == | == Entries == | ||
| Line 30: | Line 30: | ||
|} | |} | ||
Extensions also report their package ID, version, dependencies and [[SimTX API/Packets/CatalogList#Catalog types|types]], read from the manifest at upload time. | Extensions also report their package ID, version, dependencies and [[SimTX API v24/Packets/CatalogList#Catalog types|types]], read from the manifest at upload time. | ||
=== Ownership and revisions === | === Ownership and revisions === | ||
| Line 51: | Line 51: | ||
== Upload rules == | == Upload rules == | ||
The server validates every upload. A failure is reported in [[SimTX API/Packets/CatalogUploadResult|CatalogUploadResult]] with <code>ok = false</code> and a message. | The server validates every upload. A failure is reported in [[SimTX API v24/Packets/CatalogUploadResult|CatalogUploadResult]] with <code>ok = false</code> and a message. | ||
{| class="wikitable" | {| class="wikitable" | ||
| Line 77: | Line 77: | ||
|} | |} | ||
{{SimTX API navbox}} | {{SimTX API v24 navbox}} | ||
[[Category:SimTX API]] | [[Category:SimTX API v24]] | ||
[[Category:SimTX API sessions]] | [[Category:SimTX API v24 sessions]] | ||
Latest revision as of 16:13, 24 October 2026
The extension catalog is the server's shared library of Lua extensions and station presets. The official transmitter's catalog browser is built on four requests of the control session, documented here. Users' view of the catalog is described in Extension catalog; the package format is in Lua extension manifest.
Requests[edit | edit source]
| Request | Response | Permission |
|---|---|---|
| CatalogListRequest (20) | CatalogList (24) | None |
| CatalogFetch (21) | CatalogEntry (25) | None |
| CatalogUpload (22) | CatalogUploadResult (21) | catalog.publish
|
| CatalogDelete (26) | CatalogDeleteResult (29) | catalog.publish, owner only
|
All four count as heavy requests for rate limiting.
Browsing works anonymously. Publishing requires an authenticated control session: obtain a game ticket with role control (which itself requires catalog.publish) and present it in the handshake.
Entries[edit | edit source]
A catalog entry has a numeric ID, a kind, a name, an author, a revision number and a set of text files.
| Kind | Content |
|---|---|
extension |
A Lua extension package: an extension.properties manifest and one or more .lua files.
|
preset |
A station preset: exactly one .stxpreset file.
|
Extensions also report their package ID, version, dependencies and types, read from the manifest at upload time.
Ownership and revisions[edit | edit source]
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 result message is
Updated. - When another account uploads that name, the upload fails with 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[edit | edit source]
Browsing
- Send CatalogListRequest. Show the entries from CatalogList.
- When the user opens one, send CatalogFetch with its ID and read the files from CatalogEntry.
- 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
extension.propertiesand every.luafile the manifest refers to. - Send CatalogUpload. Read CatalogUploadResult. On success, it carries the entry ID.
- On failure, show the message to the user. It explains exactly which rule was broken.
Upload rules[edit | edit source]
The server validates every upload. A failure is reported in CatalogUploadResult with ok = false and a message.
| Rule | Limit |
|---|---|
| Kind | extension or preset
|
| Name | 1–64 characters after trimming; unique per server |
| Description | At most 500 characters |
| Categories | At most 12; each 1–32 characters, no commas or control characters; duplicates ignored without regard to case. Categories are free text. |
| Files | 1–64 (a preset: exactly 1) |
| File path | At most 128 characters, relative, / separators only, no empty, . or .. segments, unique without regard to case
|
| File names | Extension: extension.properties or *.lua. Preset: *.stxpreset.
|
| 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. |