Merge pull request #99 from moisseev/fuzzy-flags

Document fuzzy_check read_only default and flag uniqueness behavior

Author: vstakhov

docs/modules/fuzzy_check.md

@@ -50,7 +50,7 @@ rule "FUZZY_EXAMPLE" {
   # Hash algorithm: mumhash (default), fasthash, xxhash, siphash
   algorithm = "mumhash";
 
-  # Allow learning to this storage (default: true = read-only)
+  # Allow write operations (learning) to this storage; set true to disallow
   read_only = false;
 
   # Map flags to symbols
@@ -187,7 +187,7 @@ Each `rule` section defines a fuzzy storage connection:
 | `max_score` | float | — | Global threshold for this rule (deprecated, use per-flag). |
 | `max_hits` | int | — | Maximum matches per message for this rule. |
 | `mime_types` | array | — | MIME types to check: `["*"]`, `["application/*"]`, etc. |
-| `read_only` | boolean | `true` | If `false`, allow learning to this storage. |
+| `read_only` | boolean | `false` | If `true`, disallow learning (write operations) to this storage. |
 | `skip_unknown` | boolean | `false` | If `true`, don't add default symbol for unmatched flags. |
 | `symbol` | string | — | Default symbol for this rule. |
 | `short_text_direct_hash` | boolean | `false` | Use exact hash for texts shorter than `min_length`. |
@@ -208,6 +208,12 @@ fuzzy_map = {
 }
 ```
 
+:::warning Flag Uniqueness for Writable Rules
+Flag numbers must be unique across all rules that do not have `read_only = true`. When Rspamd performs a write operation (add or delete), it sends the request to **all** rules whose `fuzzy_map` contains the matching flag and that are not read-only—regardless of which rule matched during scanning. If two writable rules share a flag and one storage rejects writes (e.g., a public third-party server that does not permit writes from your host), a 503 error will be returned.
+
+To avoid this: use distinct flag numbers for each writable rule, or set `read_only = true` on third-party rules that should not receive write operations. Setting `read_only = true` on your own local storage rule instead will result in a 404 error when attempting to learn.
+:::
+
 Different flags allow a single storage to contain multiple hash categories:
 
 | Flag | Purpose | Example Symbol |

docs/tutorials/fuzzy_storage.md

@@ -375,13 +375,19 @@ One option is `max_score`, which specifies the threshold for a hash weight:
 
 The `mime_types` option specifies which attachment types are checked (or learned) using this fuzzy rule. This option takes a list of valid types in the following format: `["type/subtype", "*/subtype", "type/*", "*"]`, where `*` represents any valid type. In practice, it can be useful to save the hashes for all `application/*` attachments. Texts and embedded images are implicitly checked by `fuzzy_check` plugin, so there is no need to add `image/*` in the list of scanned attachments. Note that attachments and images are searched for an exact match, while texts are matched using the approximate algorithm (shingles).
 
-`read_only` is quite an important option required for storage learning. It is set to `read_only=true` by default, restricting thus a storage's learning:
+`read_only` is quite an important option required for storage learning. By default, a rule allows learning (`read_only = false`):
 
 ~~~hcl
 read_only = true; # disallow learning
-read_only = false; # allow learning
+read_only = false; # allow learning (default)
 ~~~
 
+:::warning Flag Uniqueness for Writable Rules
+Flag numbers must be unique across all rules that do not have `read_only = true`. Write operations (add/delete) are sent to **all** rules whose `fuzzy_map` contains the matching flag and that are not read-only—regardless of which rule was used for scanning. If two writable rules share a flag and one storage rejects writes (e.g., a public or third-party server that does not permit writes from your host), a 503 error will be returned.
+
+To avoid this: use distinct flag numbers for each writable rule, or explicitly set `read_only = true` on third-party rules that should not receive write operations. Setting `read_only = true` on your own local storage rule instead will result in a 404 error when attempting to learn.
+:::
+
 `Encryption_key` parameter specifies the **public** key of a storage and enables encryption for all requests.
 
 `Algorithm` parameter specifies the algorithm for generating hashes from text parts of emails (for attachments and images [blake2b](https://blake2.net/) is always used).