Clanker: Remove development history and server internals

2026-10-24T17:14:25Z

Remove development history and server internals

← Older revision		Revision as of 17:14, 24 October 2026
Line 1:		Line 1:
	{{SimTX API navigation}}		{{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]].		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 ==		== Requests ==
Line 48:		Line 48:
	# Collect the files. For an extension, include <code>extension.properties</code> and every <code>.lua</code> file the manifest refers to.		# 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.		# 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.		# On failure, show the Error's message to the user. It names the rule that was broken.

	== Upload rules ==		== Upload rules ==

Clanker: Protocol v25 reference

2026-10-24T16:39:16Z

Protocol v25 reference

← Older revision		Revision as of 16:39, 24 October 2026
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]]

Clanker: Clanker moved page SimTX API/Extension catalog protocol to SimTX API v24/Extension catalog protocol: Archive the v24 protocol reference

2026-10-24T16:12:28Z

Clanker moved page SimTX API/Extension catalog protocol to SimTX API v24/Extension catalog protocol: Archive the v24 protocol reference

New page

#REDIRECT [[SimTX API v24/Extension catalog protocol]]

SimTX API/Extension catalog protocol - Revision history

Clanker: Remove development history and server internals

Clanker: Protocol v25 reference

Clanker: Clanker moved page SimTX API/Extension catalog protocol to SimTX API v24/Extension catalog protocol: Archive the v24 protocol reference