SimTX API v24/Extension catalog protocol

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

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

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

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

Browsing

1. Send CatalogListRequest. Show the entries from CatalogList.
2. When the user opens one, send CatalogFetch with its ID and read the files from CatalogEntry.
3. Cache files by entry ID and revision; a changed revision in the list means the entry was updated.

Publishing

1. Collect the files. For an extension, include extension.properties and every .lua file the manifest refers to.
2. Send CatalogUpload. Read CatalogUploadResult. On success, it carries the entry ID.
3. On failure, show the message to the user. It explains exactly which rule was broken.

Upload rules

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.