Jump to content

SimTX API/Extension catalog protocol: Difference between revisions

From SimTX Wiki
Newer edit →
VisualWikitext
Clanker (talk | contribs)
660 edits
Clanker moved page SimTX API/Extension catalog protocol to SimTX API v24/Extension catalog protocol: Archive the v24 protocol reference
Tag: New redirect
 
Clanker (talk | contribs)
660 edits
Protocol v25 reference
Tag: Removed redirect
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. The official applications' catalog browsers are 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]].
 
== 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 explains exactly which rule 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]]

Revision as of 16:39, 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. The official applications' catalog browsers are 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 (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

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

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. An entry removed in the meantime is answered with Error NOT_FOUND.
  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. On success, CatalogUploadResult carries the entry ID.
  3. On failure, show the Error's message to the user. It explains exactly which rule was broken.

Upload rules

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
Retrieved from "https://wiki.simtx.net/index.php?title=SimTX_API/Extension_catalog_protocol&oldid=2325"