[RFC proxmox 02/22] firewall-api-types: add README.md

[Dietmar Maurer <dietmar@proxmox.com>]

Signed-off-by: Dietmar Maurer <dietmar@proxmox.com>
---
 proxmox-firewall-api-types/README.md | 54 ++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 proxmox-firewall-api-types/README.md

diff --git a/proxmox-firewall-api-types/README.md b/proxmox-firewall-api-types/README.md
new file mode 100644
index 00000000..1ae22118
--- /dev/null
+++ b/proxmox-firewall-api-types/README.md
@@ -0,0 +1,54 @@
+# proxmox-firewall-api-types
+
+Strongly typed Rust definitions for the Proxmox VE Firewall API.
+
+## Motivation
+
+The current PVE firewall implementation is written in Perl, and Rust type
+definitions can be auto-generated from its API schemas. However, many of the
+more complex types are represented as opaque strings, which limits type safety.
+
+Verifiers for complex types like ports and address matches cannot be generated
+automatically, so we need to implement them manually anyway.
+
+To address this, the crate provides hand-crafted Rust types that parse and validate these
+string-encoded values into proper enums and structs, while remaining fully
+compatible with the existing API wire format. The initial type definitions were
+seeded from the auto-generated `pve-api-types` crate and then refined by hand.
+
+Dependencies are minimal, so that we can use this crate for wasm targets (GUI).
+
+## Compatibility
+
+All types must serialize and deserialize to the same JSON wire format that the
+existing Perl-based PVE API produces and consumes. There is currently no
+automated compatibility test against the live Perl API, so changes must be
+verified manually.
+
+Key techniques used to maintain wire-format compatibility:
+
+- **Perl-specific deserializers** — The Perl API encodes booleans and integers
+  as strings. Fields that come from Perl use custom deserializers such as
+  `proxmox_serde::perl::deserialize_bool` and `deserialize_u64` to accept
+  these representations.
+- **Serde renames** — `#[serde(rename = "...")]` and `#[serde(rename_all = "kebab-case")]`
+  ensure that Rust field and variant names map to the exact keys and values
+  the Perl API expects (e.g. `icmp-type`, `macro`, `type`).
+- **Forward-compatible enums** — When the `enum-fallback` feature is enabled,
+  enums gain an `UnknownEnumValue` catch-all variant (backed by
+  `proxmox-fixed-string`) so that new values added in a future API version
+  can be deserialized without errors.
+
+When adding or modifying types, compare the serde output against the
+corresponding Perl API endpoint to ensure the JSON representation matches.
+
+## Features
+
+- **`enum-fallback`** — Enables an `UnknownEnumValue` catch-all variant on
+  enums (backed by `proxmox-fixed-string`) for forward-compatible
+  deserialization of values added in newer API versions.
+
+## Usage
+
+- All public types are re-exported from the crate root.
+- Every type implements `serde::Serialize` / `Deserialize`.
-- 
2.47.3