{"id":21571180,"url":"https://github.com/cheprasov/specification-protocol-userpro","last_synced_at":"2026-03-19T20:53:06.920Z","repository":{"id":146911619,"uuid":"106750527","full_name":"cheprasov/specification-protocol-userpro","owner":"cheprasov","description":"Universal serialization protocol (USERPRO)","archived":false,"fork":false,"pushed_at":"2022-07-15T23:26:28.000Z","size":8,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-24T12:45:46.901Z","etag":null,"topics":["protocol","serialization","specification","userpro"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cheprasov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-10-12T22:10:35.000Z","updated_at":"2022-07-15T23:27:15.000Z","dependencies_parsed_at":"2024-03-27T07:15:06.930Z","dependency_job_id":null,"html_url":"https://github.com/cheprasov/specification-protocol-userpro","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/cheprasov%2Fspecification-protocol-userpro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheprasov%2Fspecification-protocol-userpro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheprasov%2Fspecification-protocol-userpro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheprasov%2Fspecification-protocol-userpro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cheprasov","download_url":"https://codeload.github.com/cheprasov/specification-protocol-userpro/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244166758,"owners_count":20409179,"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":["protocol","serialization","specification","userpro"],"created_at":"2024-11-24T11:15:12.161Z","updated_at":"2026-01-03T08:41:31.509Z","avatar_url":"https://github.com/cheprasov.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"SPECIFICATION of UNIVERSAL SERIALIZATION PROTOCOL (USERPRO)\n===\nThe specification describes how clients communicate with some a server using a protocol called **USERPRO** (Universal Serialization Protocol). While the protocol was designed specifically for client-server software projects and microservices.\n\nUSERPRO is a compromise between the following things:\n* Versatility.\n* Stream processing.\n* Simple to implement.\n* Fast to parse.\n* Human readable.\n* Support data structure.\n\nWhile comparable in performance to a binary protocol the protocol is significantly simpler to implement in most very high level languages, reducing the number of bugs in client software.\n\nUSERPRO can serialize different data types like integers, strings, arrays, maps, booleans, errors, bulks and other.Requests are sent from the client to the server as any type of data (array, string and other), representing the arguments of the command to execute, based on the server implementation. The server replies with a command-specific structure of data.\n\nUSERPRO is binary-safe and does not require processing of bulk data transferred from one process to another, because it uses prefixed-length to transfer bulk data.\nNote: the protocol outlined here is only used for client-server communication.\n\n### Networking layer\n\nA client connects to a server creating a TCP connection to some port.\nWhile USERPRO is technically non-TCP specific, in the context of the protocol is only used with TCP connections (or equivalent stream oriented connections like Unix sockets).\n\nThe protocol is a simple request-response protocol.\n\n### USERPRO protocol description\n\nUSERPRO is actually a serialization protocol that supports the following data types: Simple Strings, Integers, Floats, Booleans, Arrays, Maps, Errors, Bulk Strings and other.\n\nThe way USERPRO as a request-response protocol is the following:\n* Clients send commands to a server as a USERPRO Data.\n* The server replies with one of the USERPRO types according to the command implementation.\n\nIn USERPRO, the type of some data depends on the first byte:\n* For **Integers** the first byte of the reply is \"**i**\"\n* For **Floats** the first byte of the reply is \"**f**\"\n* For **Booleans** the first byte of the reply is \"**b**\"\n* For **Simple Strings (Lines)** (without newlines symbols \"\\r\" or \"\\n\") the first byte of the reply is \"**l**\"\n* For **Bulk or Multilines Strings** the first byte of the reply is \"**s**\"\n* For **Arrays** the first byte of the reply is \"**a**\"\n* For **Maps** the first byte of the reply is \"**m**\"\n* For **Predefined Constants** the first byte of the reply is \"**c**\"\n* For **Errors** the first byte of the reply is \"**e**\"\n\nAdditionally USERPRO is able to represent a Null, NaN, or Infinity values using a special variation of Predefined Constants as specified later.\n\nIn USERPRO different parts of the protocol are always terminated with \"\\n\" (LF).\n\n### USERPRO Integers\n\nThis type is just a LF terminated string representing an integer, prefixed by a \"**i**\" byte. For example \"`i0\\n`\", \"`i-33\\n`\" or \"`i42\\n`\" are integer replies.\n\n### USERPRO Floats\n\nThis type is just a LF terminated string representing an float, prefixed by a \"**f**\" byte. For example \"`f0.0\\n`\", \"`f-3.3\\n`\" or \"`f4.2\\n`\" are float replies.\n\n### USERPRO Booleans\n\nThis type is just a LF terminated string representing an booleab, prefixed by a \"**b**\" byte. For example \"`b0\\n`\" (false), \"`b1\\n`\" (true) are boolean replies.\n\n### USERPRO Simple Strings (Lines)\n\nSimple Strings are encoded in the following way: \"**l**\" byte, followed by a string that cannot contain a CR or LF character (no newlines are allowed), terminated by LF (that is \"\\n\").\n\nSimple Strings are used to transmit non binary safe strings with minimal overhead. For example some reply with just \"OK\" on success, that as a USERPRO Simple String is encoded with the following 4 bytes:\n\"`lOK\\n`\"\n\nIn order to send binary-safe strings, USERPRO Bulk Strings are used instead.\n\nWhen server replies with a Simple String, a client library should return to the caller a string composed of the first character after the \"**l**\" up to the end of the string, excluding the final **LF** byte.\n\n### USERPRO Bulk or Multilines Strings\n\nBulk or Multilines Strings are used in order to represent a single binary safe string.\n\nBulk Strings are encoded in the following way:\nA \"**s**\" byte followed by the number of bytes composing the string (a prefixed length), terminated by **LF**. Then the actual string data. A final **LF**.\n\nSo the string \"foobar\" is encoded as follows: \"`s6\\nfoobar\\n`\"\n\nWhen an empty string, Bulk Strings are encoded without string data and second **LF**, is just: \"`s0\\n`\"\n\n### USERPRO Arrays\n\nArray is a collection of USERPRO type elements. USERPRO Arrays are sent using the following format:\nA \"**a**\" character as the first byte, followed by the number of elements in the array as a decimal number, followed by **LF**. An additional USERPRO type for every element of the Array.\n\nSo an empty Array is just the following: \"`a0\\n`\"\n\nWhile an array of two USERPRO Bulk Strings \"foo\" and \"bar\" is encoded as:\n\"a2\\ns3\\nfoo\\ns3\\nbar\\n\"\nAs you can see after the a\u003ccount\u003eLF part prefixing the array, the other data types composing the array are just concatenated one after the other. For example an Array of three integers is encoded as follows: \"`a3\\ni1\\ni2\\ni3\\n`\"\nArrays can contain mixed types, it's not necessary for the elements to be of the same type. For instance, a list of 2 integers and a bulk string can be encoded as the follows:\n(The reply was split into multiple lines for clarity).\n```\na3\\n\ni10\\n\ni42\\n\ns6\\n\nfoobar\\n\n```\nThe first line the server sent is `a3\\n` in order to specify that 3 replies will follow. Then every reply constituting the items of the Multi Bulk reply are transmitted.\nArrays of arrays are possible in USERPRO. For example an array of two arrays is encoded as follows:\n(The format was split into multiple lines to make it easier to read).\n```\na2\\n\na3\\n\ni1\\n\ni2\\n\ni3\\n\na2\\n\nlFoo\\n\nlBar\\n\n```\n\nThe above USERPRO data type encodes a two elements Array consisting of an Array that contains three Integers 1, 2, 3 and an array of two Simple Strings.\n\n### USERPRO Maps\n\nMap is a hash table. It has key-value structure. USERPRO Maps are sent using the following format:\nA \"**m**\" character as the first byte, followed by the number of elements in the map as a decimal number, followed by **LF**. An additional USERPRO two types for every element of the map as key and value.\n\nSo an empty map is just the following: \"`m0\\n`\"\n\nMaps can contain mixed types for keys or values.\n\nExample: let's move json user data `{\"name\": \"Alexander\",\"age\":33, \"city\":\"London\"}` to USERPRO map:\n```\nm3\\n\nlname\\n\nlAlexander\\n\nlage\\n\ni33\\n\nlcity\\n\nlLondon\\n\n```\n\n### USERPRO Predefined Constants\n\nThis type is just a LF terminated string representing an predefined constant, prefixed by a \"**c**\" byte.\n\nPredefined Constants are:\n\n| Constant | Description | Encoded as |\n|-----------|------------------------------------------------------------|------------|\n| Null | The special NULL value represents a variable with no value | `cnull\\n` |\n| NaN | The value for Not a numbers | `cnan\\n` |\n| -Infinity | Negative infinity | `c-inf\\n` |\n| +Infinity | Positive infinite | `c+inf\\n` |\n\n\n### USERPRO Errors\n\nUSERPRO has a specific data type for errors. Actually errors are exactly like USERPRO Bulk or Multilines Strings, but the first character is a minus \"**e**\" character instead of \"**s**\". Errors are treated by clients as exceptions, and the string that composes the Error type is the error message itself.\nThe basic format is: \"`e13\\nError message\\n`\"\nError replies are only sent when something wrong happens, for instance if you try to perform an operation against the wrong data type, or if the command does not exist and so forth. An exception should be raised by the library client when an Error Reply is received.\n\n### USERPRO Data structures\n\n...\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcheprasov%2Fspecification-protocol-userpro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcheprasov%2Fspecification-protocol-userpro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcheprasov%2Fspecification-protocol-userpro/lists"}