SimTX API/Extension catalog protocol: Difference between revisions

Latest revision as of 17:14, 24 October 2026

API overviewQuick startHandshakeFramingAll messagesData typesStationsAccount serviceLimits and errorsv24 reference

The extension catalog is the server's shared library of Lua extensions and station presets. It is accessed with 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 (36)	CatalogList (36)	None
CatalogFetch (37)	CatalogEntry (37)	None
CatalogUpload (38)	CatalogUploadResult (38)	`catalog.publish`
CatalogDelete (39)	CatalogDeleteResult (39)	`catalog.publish`, owner only

The numbers are the frame member numbers. All four count as heavy requests for rate limiting. Each carries a request_id that its response echoes. A refused request is answered with Error carrying that request_id and a message that says what to fix; the session continues.

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 hello.

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 CatalogUploadResult has updated = true.
When another account uploads that name, the upload fails with Error FORBIDDEN: 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. An entry removed in the meantime is answered with Error NOT_FOUND.
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.properties and every .lua 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[edit | edit source]

The server validates every upload and reports the first problem found in an Error.

Rule	Limit
Kind	`extension` or `preset`
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, `/` 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.

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

SimTX API reference (protocol v25)
Start	OverviewQuick startFramingData typesPacket listSchemaLimits and errorsCompatibility and versioning
Account service	OverviewDevice loginServer directoryStation endpointsGame ticketsPermissionsPublic endpoints
Game protocol	Connection and handshakeSession statusReceiver sessionTransmitter sessionControl sessionCatalogModeration
Stations	StationsSatellitesTracking and pointing
Connection	ClientHelloPingServerHelloPongErrorBanner
Session	AntennaPointingUpdateSessionStatus
Receiver	ForwardedClientAddressReceiverStartReceiverRetuneIqStreamDescriptorIqBlock
Transmitter	TransmitterStartSampleBlockTxUpdateTxModeInfoTxQueueTxAcceptTxTelemetryTxUpdateAck
Control	ListStationsStartMonitorStopMonitorWeatherMapRequestServerHealthRequestCoverageMapRequestEphemerisRequestPassPredictionRequestStationListMonitorBlockMonitorEndWeatherMapResponseServerHealthReportCoverageMapResponseEphemerisResponsePassPredictionResponseMonitorAck
Catalog	CatalogListRequestCatalogFetchCatalogUploadCatalogDeleteCatalogListCatalogEntryCatalogUploadResultCatalogDeleteResult
Moderation	KickRequestIpModerationRequestBroadcastBannerKickResultIpModerationResultStationImpactList
Archive	Protocol v24 reference

@@ Line 1: / Line 1: @@
-#REDIRECT [[SimTX API v24/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]]