{"id":17046529,"url":"https://github.com/tkellogg/mqtt-resource-directory","last_synced_at":"2025-03-23T03:20:33.119Z","repository":{"id":24700835,"uuid":"28112250","full_name":"tkellogg/mqtt-resource-directory","owner":"tkellogg","description":"A spec for a Resource Directory implementation for MQTT","archived":false,"fork":false,"pushed_at":"2014-12-17T05:01:59.000Z","size":220,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-01-28T09:44:57.651Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tkellogg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-12-16T23:46:51.000Z","updated_at":"2015-01-16T14:51:54.000Z","dependencies_parsed_at":"2022-08-06T02:15:35.765Z","dependency_job_id":null,"html_url":"https://github.com/tkellogg/mqtt-resource-directory","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkellogg%2Fmqtt-resource-directory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkellogg%2Fmqtt-resource-directory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkellogg%2Fmqtt-resource-directory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkellogg%2Fmqtt-resource-directory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tkellogg","download_url":"https://codeload.github.com/tkellogg/mqtt-resource-directory/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245049447,"owners_count":20552682,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-14T09:46:38.181Z","updated_at":"2025-03-23T03:20:33.094Z","avatar_url":"https://github.com/tkellogg.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"MQTT Resource Directory\n=======================\n\nThis specification is an attempt to adapt the concepts from [CoAP Resource Directory][1] to MQTT.\n\n\nAbstract\n--------\n\nMQTT doesn't allow for custom headers, which is fine since it's designed for constrained environments. That also means there's no obvious place for metadata like Content-Type or maximum message size. In other attempts to solve this problem, metadata was stuffed into the topic. In contrast, the resource directory approach keeps message size small and allows for a self-describing data format. \n\n\n1. Introduction\n---------------\n\nMQTT is a popular publish/subscribe protocol that has seen major adoption within the Internet of Things where constrained devices need to send and receive telemetry data. Since the protocol was designed to be extremely compact, there is very little room left over for transmitting metadata. This specification solves this problem by standardizing a topic space to be used as a resource directory for metadata about certain topic spaces or the broker itself.\n\n\n### 1.1 Goals\n\nMQTT is currently used mostly in constrained environments were data size must be kept at a minimum so users tend to feel constrained on the amount of data they are sending as well as the simplicity. \n\n* *Secure*. Or at least the ability to be secure since many MQTT brokers don't implement any kind of topic level security. \n* *No libraries*. While this spec may be implemented by clients, this spec should be simple enough that anyone could query the resource directory and parse the results without the use of any external libraries. More importantly, many of the embedded engineers that we have talked with have been aprehensive about including any external dependencies.\n* *Extensibility*. This spec doesn't presume to understand all goals that other people may have. We only want to standardize methods to communicate metadata.\n* *No inflated messages*. Metadata must not be communicated through topic names or through a payload envelope. Use of an external Resource Directory lets the client query metadata only when needed and never more. Its hard to rationalize the inflation messages in hot topics that see high message throughput. \n* *Determinism*. A single GET request should return only a single message. If there are many messages returned, it becomes difficult for the client to know when they have a full listing and to stop listening. This helps achieve the goal of requiring no libraries to query the resource directory.\n* *Zero coordination*. MQTT does not have constructs for ACID transactions, so no part of this spec can assume that the client can GET the value of a topic and then PUT to update it. PUT should operate only as \"add\" or \"replace\" and never as \"PATCH\" or \"update one or more properties\".\n\n*Note: I'm not sure that I can have both Determinism and Zero Coordination. If not, than I choose Zero Coordination. As such, I've added INDEX requests, which will be avoided as much as possible.*\n \n\n### 1.2 Web Linking\n\nIn lieu of the above stated goals, messages in this Resource Directory MUST use web linking as specified in [RFC 5988][3]. This format is easy to parse and multiple entries can be separated by newlines. This also gives us the flexibility to define custom attributes, which enables this spec to remain flexible.\n\n\n2. Terminology\n--------------\n\nThe key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"NOT RECOMMENDED\", \"MAY\", and \"OPTIONAL\" in this document are to be interpreted as described in [RFC2119][4].\n\nThis specification requires that readers be familiar with all terms and concepts from [MQTT version 3.1.1][2].\n\nThese are some additional terms used within this specification:\n\n* **Resource Directory topic** - Any topic starting with the string `$rd/`. There MUST NOT be any characters before this string.\n* **PUT Request** - A PUBLISH message with the retained option set to `true` to a Resource Directory topic.\n* **GET Request** - A SUBSCRIBE message sent to a Resource Directory topic. Each topic pattern MUST NOT contain any wildcards, but a singe GET request MAY contain multiple topic patterns.\n* **INDEX Request** - A SUBSCRIBE message sent to a Resource Directory topic that contains exactly one `+` wildcard as the last character of the topic pattern.\n* **DELETE Request** - A PUBLISH message with the retained option set to `true` and an empty (zero byte) payload to a Resource Directory topic.\n \n\n### 2.1 Details on GET requests\n\nA GET request is a SUBSCRIBE message sent to a Resource Directory topic. Each topic pattern MUST NOT contain any wildcards, so it will only retrieve a single PUBLISH message. However, a SUBSCRIBE message MAY contain many topic subscriptions, but the client will still know exactly how many PUBLISH messages to listen for.\n\nWhen the client receives all expected messages, it SHOULD send a UNSUBSCRIBE message to terminate the GET request. If the client has not received one (1) or more expected messages after thirty (30) seconds, it MAY send an UNSUBSCRIBE message to terminate the request.\n\n\n### 2.2 Details on INDEX requests\n\nAn INDEX request is functionally the same as a GET request except that it is non-deterministic. An INDEX request may return zero to many responses that will arrive in no specific order. A client MAY choose to terminate this request by sending an UNSUBSCRIBE message. If the client chooses to terminate the request, it SHOULD wait thirty (30) seconds after the last message has been recieved before sending the UNSUBSCRIBE message. If no messages are received, the client may send the UNSUBSCRIBE message thirty (30) seconds after sending the original UNSUBSCRIBE message.\n\n\n3. Well-Known Functions\n-----------------------\n\nThis section describes functions that augment the core MQTT protocol with metadata. Each of these is OPTIONAL. An INDEX request to `$rd/well-known/+` MAY be used to get a full listing of functions. \n\n\n### 3.1 Error Messages\n\nThe 3.1.1 specification does not allow for a way to communicate errors so this is a stop gap measure. In this feature, the broker SHOULD PUT values to a topic that only that client can subscribe to.\n\nIf the broker supports this feature, it MUST publish a retained message to `$rd/well-known/errors` with a payload in CoRE Link Format. In the topic given in the payload, the broker SHOULD include the string `$id`. The client MUST replace all instances of `$id` with it's own client ID.\n\n**Examples**\n\n| Link           | Client ID         | Topic                  |\n|----------------|-------------------|------------------------|\n| \u003c$errors/$id\u003e  | foobar            | $errors/foobar         |\n\n\n\n\n\n [1]: https://tools.ietf.org/html/draft-ietf-core-resource-directory-02\n [2]: http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html\n [3]: https://tools.ietf.org/html/rfc5988\n [4]: https://tools.ietf.org/html/rfc2119\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftkellogg%2Fmqtt-resource-directory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftkellogg%2Fmqtt-resource-directory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftkellogg%2Fmqtt-resource-directory/lists"}