From e7def56ff07282005ab603cd0f695d201da80ad5 Mon Sep 17 00:00:00 2001 From: dualfroz Date: Sat, 3 Oct 2026 02:24:35 +0200 Subject: [PATCH] docs: Document the 128 characters limit on collection, bucket and object names Values longer than 128 bytes or with non-ASCII characters are rejected by `StoreItemPart::from_str` with `ERR invalid_argument(...)`, but the protocol did not say so. Closes #319 --- PROTOCOL.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/PROTOCOL.md b/PROTOCOL.md index 1afb9f2..5cb6017 100644 --- a/PROTOCOL.md +++ b/PROTOCOL.md @@ -18,6 +18,7 @@ _Refer to sections below to interact with Sonic._ 1. Each command sent must be terminated with a new line character (`\n`) as to commit the command to the server; 2. Upon starting a Sonic Channel session, your library should read the `buffer(20000)` parameter in the `STARTED` response, and use this value (in bytes) as to know when a command data should be truncated and split in multiple sub-commands (to avoid buffer overflows, ie. sending too much data in a single command); +3. The ``, `` and `` values of any command must be 1 to 128 ASCII characters long, otherwise the command is rejected with `ERR invalid_argument(InvalidCollection)`, `ERR invalid_argument(InvalidBucket)` or `ERR invalid_argument(InvalidObject)`; --- @@ -44,8 +45,8 @@ _The Sonic Channel Search mode is used for querying the search index. Once in th **⏩ Syntax terminology:** -* ``: index collection (ie. what you search in, eg. `messages`, `products`, etc.); -* ``: index bucket name (ie. user-specific search classifier in the collection if you have any eg. `user-1, user-2, ..`, otherwise use a common bucket name eg. `generic, default, common, ..`); +* ``: index collection (ie. what you search in, eg. `messages`, `products`, etc.), 1 to 128 ASCII characters long; +* ``: index bucket name (ie. user-specific search classifier in the collection if you have any eg. `user-1, user-2, ..`, otherwise use a common bucket name eg. `generic, default, common, ..`), 1 to 128 ASCII characters long; * ``: text for search terms (between quotes); * ``: a positive integer number; set within allowed maximum & minimum limits; * ``: an ISO 639-3 locale code eg. `eng` for English (if set, the locale must be a valid ISO 639-3 code; if set to `none`, lexing will be disabled; if not set, the locale will be guessed from text); @@ -120,9 +121,9 @@ Note that Sonic doesn’t provide an `UPDATE` command, because of the lossy natu **⏩ Syntax terminology:** -* ``: index collection (ie. what you search in, eg. `messages`, `products`, etc.); -* ``: index bucket name (ie. user-specific search classifier in the collection if you have any eg. `user-1, user-2, ..`, otherwise use a common bucket name eg. `generic, default, common, ..`); -* ``: object identifier that refers to an entity in an external database, where the searched object is stored (eg. you use Sonic to index CRM contacts by name; full CRM contact data is stored in a MySQL database; in this case the object identifier in Sonic will be the MySQL primary key for the CRM contact); +* ``: index collection (ie. what you search in, eg. `messages`, `products`, etc.), 1 to 128 ASCII characters long; +* ``: index bucket name (ie. user-specific search classifier in the collection if you have any eg. `user-1, user-2, ..`, otherwise use a common bucket name eg. `generic, default, common, ..`), 1 to 128 ASCII characters long; +* ``: object identifier that refers to an entity in an external database, where the searched object is stored (eg. you use Sonic to index CRM contacts by name; full CRM contact data is stored in a MySQL database; in this case the object identifier in Sonic will be the MySQL primary key for the CRM contact), 1 to 128 ASCII characters long; * ``: search text to be indexed (can be a single word, or a longer text; within maximum length safety limits; should be quoted using `"` quotes; internal quotes should be escaped using `\"`); * ``: an ISO 639-3 locale code eg. `eng` for English (if set, the locale must be a valid ISO 639-3 code; if set to `none`, lexing will be disabled; if not set, the locale will be guessed from text); * ``: help manual to be shown (available manuals: `commands`);