diff --git a/docs/docs/design/type-bounds.md b/docs/docs/design/type-bounds.md index 03f19f0..2a2afc3 100644 --- a/docs/docs/design/type-bounds.md +++ b/docs/docs/design/type-bounds.md @@ -1,6 +1,6 @@ # Bounds on types -Status: **accepted 2026-11-02, not implemented** · +Status: **accepted 2026-11-02; steps 1–6 shipped, 7–12 in progress** · [core#98](https://github.com/ComlineProject/core/issues/98) · Decided through [the proposals](../proposals/type-bounds/index.md): [Proposal D](../proposals/type-bounds/max-only.md), with diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md index 1397275..f955599 100755 --- a/docs/docs/getting-started.md +++ b/docs/docs/getting-started.md @@ -51,11 +51,17 @@ enum Language { } struct Greeting { - message: string + message: char[max 256] language: Language } ``` +Every string and list needs a maximum, so a decoder can refuse an oversized +value before allocating it. `char[max 256]` is a string of at most 256 +characters. To set one for the whole package instead, see +[default maximums](guide/idl/settings.md#default-maximums); the rules are in +[Types](guide/idl/types.md#bounds). + ## Build ```bash diff --git a/docs/docs/guide/idl/annotations.md b/docs/docs/guide/idl/annotations.md index fa3319c..03c79b0 100644 --- a/docs/docs/guide/idl/annotations.md +++ b/docs/docs/guide/idl/annotations.md @@ -10,7 +10,7 @@ protocol Mail { function send(message: Message) -> bool; @idempotent - function fetch_inbox() -> Message[]; + function fetch_inbox() -> Message[max 100]; } ``` @@ -34,6 +34,7 @@ build. | Annotation | On | What it does | Details | |---|---|---|---| | `@validators` | a field, a `type` alias | runs named checks on the value | [Validators](validator.md#using-one-validators) | +| `@max_depth` | a struct | how deeply a struct that can contain itself nests | [`@max_depth`](#max_depth) | | `@deprecated` | a struct, a `type` alias | warns wherever it's used; the value is `true` or a message | [Types](types.md#type-aliases) | | `@settings` | any declaration | applies a named settings preset | [Settings](settings.md#named-presets-settings) | | `@framing` | a protocol | how calls are framed on the wire | [Protocols](protocol.md#annotations) | @@ -51,6 +52,32 @@ can rely on. Any other `@key` is allowed and kept in the frozen schema, so a tool of your own can read it. Comline doesn't check it. +## `@max_depth` + +```ids +@max_depth = 8 +struct Comment { + text: char[max 500] + replies: Comment[max 20] +} +``` + +A struct that can contain itself, directly or through other structs, fields, +arrays, unions, optionals or aliases, has no natural end to its size. `@max_depth` +says how many levels deep a value may nest, and a decoder refuses one nested +deeper. + +- **The value is an integer.** +- **Every such struct needs one,** or a default from the + [`bounds.depth.max`](settings.md#default-maximums) setting, which `@max_depth` + overrides. Without either, the build fails naming the struct: + `struct `Comment` can contain itself, and has no depth limit`. +- **It is the third way to bound a message:** together with the maxima on + strings and arrays ([Bounds](types.md#bounds)) it gives every message a + worst-case size. A protocol that gives up bounded size with + [`@unverified`](protocol.md#giving-up-a-guarantee) covers a struct it reaches. +- **The limit is stored resolved,** so changing it changes the type. + ## In the editor Hovering an annotation shows what it does, where it applies, its default, and diff --git a/docs/docs/guide/idl/const.md b/docs/docs/guide/idl/const.md index ec16ff4..e259952 100644 --- a/docs/docs/guide/idl/const.md +++ b/docs/docs/guide/idl/const.md @@ -50,10 +50,36 @@ it's written for: ```ids struct Person { - name: string = DEFAULT_NAME + name: char[max 32] = DEFAULT_NAME worlds: u8 = WORLD_COUNT } ``` -Array sizes currently take an integer literal only (`Article[10]`), not a -constant name. +## Sizes from constants + +An array's size can be a constant, in a maximum or an exact length: + +```ids +const NAME_MAX: u8 = 32 +const LIMIT: u32 = 500 + +struct Customer { + name: char[max NAME_MAX] + code: char[NAME_MAX] + orders: Order[max LIMIT] + chunk: u8[max u16::MAX] +} +``` + +- **It names an unsigned integer constant:** declared `u8`, `u16`, `u32` or + `u64`, in this schema or another (`pkg::mod::NAME_MAX`), or an unsigned type's bound such as `u16::MAX`. A signed + or non-integer constant, or a name that isn't a constant, is a build error + saying so. +- **It is stored resolved.** The stored schema holds the number, so the + maximum is the same wherever the constant came from, and changing the + constant changes the type, which is a breaking change like any other bound + change. +- **The same limits apply:** at least 1 and at most `u32::MAX`, so a constant of + `0` is an error where it is used as a size. + +See [Bounds](types.md#bounds) for what a maximum means. diff --git a/docs/docs/guide/idl/docstrings.md b/docs/docs/guide/idl/docstrings.md index 8771148..23af531 100755 --- a/docs/docs/guide/idl/docstrings.md +++ b/docs/docs/guide/idl/docstrings.md @@ -24,7 +24,7 @@ ordinary comment and is discarded. /// A message routed through the mail protocol. struct Message { /// Plain-text body, UTF-8. - body: string + body: char[max 4096] } ``` diff --git a/docs/docs/guide/idl/error.md b/docs/docs/guide/idl/error.md index 4805011..5538610 100644 --- a/docs/docs/guide/idl/error.md +++ b/docs/docs/guide/idl/error.md @@ -7,7 +7,7 @@ has a required `message` and, optionally, fields. /// Raised when a message is sent to an unknown recipient. error RecipientNotFound { message = f"no recipient named {self.name}" - name: string + name: char[max 64] } ``` diff --git a/docs/docs/guide/idl/index.md b/docs/docs/guide/idl/index.md index 3fa1739..3e095df 100755 --- a/docs/docs/guide/idl/index.md +++ b/docs/docs/guide/idl/index.md @@ -17,9 +17,9 @@ enum Language { /// A greeting in a given language. struct Greeting { - message: string + message: char[max GREETING_MAX] language: Language - optional sender: string + optional sender: char[max 64] } protocol Greeter { diff --git a/docs/docs/guide/idl/protocol.md b/docs/docs/guide/idl/protocol.md index 2ce1120..4b30f0d 100755 --- a/docs/docs/guide/idl/protocol.md +++ b/docs/docs/guide/idl/protocol.md @@ -6,7 +6,7 @@ set of **functions** a caller can invoke. ```ids linenums="1" protocol Mail { function send_message(message: Message) -> bool; - function fetch_inbox() -> Message[]; + function fetch_inbox() -> Message[max 100]; function poke(); } ``` @@ -32,7 +32,7 @@ function NAME( [args] ) [-> ReturnType] [! ErrorName, ...] ; protocol Mail { @timeout_ms=1000 - function send_message(message: Message) -> string ! RecipientNotFound; + function send_message(message: Message) -> char[max 64] ! RecipientNotFound; } ``` @@ -86,7 +86,7 @@ A `@key=value` annotation on the `protocol` itself configures the whole service. ```ids linenums="1" @framing = "jsonrpc" protocol Mail { - function send_message(message: Message) -> string ! RecipientNotFound; + function send_message(message: Message) -> char[max 64] ! RecipientNotFound; } ``` @@ -130,12 +130,12 @@ a message or to ask the client something mid-request. ```ids linenums="1" protocol Chat { - function send(text: string) -> u64; + function send(text: char[max 1024]) -> u64; } @provider = Client protocol Events { - function message(text: string) -> bool; + function message(text: char[max 1024]) -> bool; function ping(); } ``` @@ -181,13 +181,13 @@ any other is a reply. ```ids linenums="1" @framing = "jsonrpc" protocol Chat { - function send(text: string) -> u64; + function send(text: char[max 1024]) -> u64; } @provider = Client @framing = { name = "jsonrpc", method_names = qualified } protocol Events { - function message(text: string) -> bool; + function message(text: char[max 1024]) -> bool; function ping(); } ``` diff --git a/docs/docs/guide/idl/settings.md b/docs/docs/guide/idl/settings.md index 8160f3a..888891d 100755 --- a/docs/docs/guide/idl/settings.md +++ b/docs/docs/guide/idl/settings.md @@ -107,11 +107,12 @@ are permission toggles taking a boolean (`true` / `false`): - `` optionally narrows to one member of that category — an annotation's name, or a validator's name. -Two keys are not permission toggles, so not every key ends in `.allowed` +Three keys are not permission toggles, so not every key ends in `.allowed` and not every value is a boolean: | Key | Value | |---|---| +| `bounds..max` | a positive integer; see [Default maximums](#default-maximums) | | `diagnostics."".level` | one of `allow`, `hint`, `info`, `warn`, `error` | | `mode` | the bare keyword `replace` | @@ -147,6 +148,64 @@ Examples: No key at any level means **allowed**, with one named exception — see below. +## Default maximums + +Every string and dynamic array needs a [maximum](types.md#bounds). Where a type +writes none, the `bounds..max` settings supply one: + +| Key | Default for | Unit | Range | +|---|---|---|---| +| `bounds.string.max` | a `string`, or `char[]` | characters (Unicode scalar values) | 1 to 4294967295 | +| `bounds.array.max` | a dynamic array, `T[]` | items | 1 to 4294967295 | +| `bounds.depth.max` | a struct that can contain itself, with no [`@max_depth`](annotations.md#max_depth) | levels of nesting | at least 1 | + +```idp linenums="1" +settings = { + bounds = { + string = { max = 256 } + array = { max = 1024 } + depth = { max = 16 } + } +} +``` + +In a `.ids` file the same is `bounds.string.max = 256`. + +- **There is no built-in default.** A package that sets none must write a maximum + at every string and list, or give bounded size up with + [`@unverified`](protocol.md#giving-up-a-guarantee). Any other name under + `bounds.` (`bounds.bytes.max`) is an unrecognised key, and `0` or a + non-integer is a build error. +- **A maximum written in the type wins.** `char[max 8]` stays 8 under any default. +- **It layers like any setting:** package, then schema, then a `@settings` + preset. A key scoped to a position goes before the global one: + `struct.field.bounds.string.max`, `error.field.bounds.array.max`, + `protocol.function.bounds.string.max` (arguments and returns), and + `struct.bounds.depth.max`. + Aliases and validator properties take the global key only. +- **A default is stored resolved** at each position it reaches, so the frozen + schema says what every position holds, and changing a default changes the + type wherever it lands, a breaking change for the package. +- **It reaches only this package's positions.** A dependency's types keep the + maxima resolved in the dependency; a consumer's default doesn't loosen or + tighten them. + +```ids linenums="1" +settings { + bounds.string.max = 64 +} + +settings Long { + bounds.string.max = 4096 +} + +struct Post { + title: string // 64 + @settings = Long + body: string // 4096 +} +``` + ## Enforcement A forbidden annotation or validator reference is always a **hard build diff --git a/docs/docs/guide/idl/structure.md b/docs/docs/guide/idl/structure.md index 2d32596..7376d28 100755 --- a/docs/docs/guide/idl/structure.md +++ b/docs/docs/guide/idl/structure.md @@ -5,9 +5,9 @@ carries typed **fields**. ```ids linenums="1" struct Message { - sender: string - recipient: string - body: string + sender: char[max 64] + recipient: char[max 64] + body: char[max 4096] priority: u8 } ``` @@ -19,8 +19,8 @@ marked `optional` and may carry a default. ```ids linenums="1" struct Message { - body: string - optional subject: string + body: char[max 4096] + optional subject: char[max 128] priority: u8 = 1 language: Language = default } @@ -35,9 +35,9 @@ struct Message { ## Field types -A field can be any [type](types.md): a primitive (`u32`, `bool`, `string`), a +A field can be any [type](types.md): a primitive (`u32`, `bool`, `char[max 64]`), a `struct`, `enum` or `type` alias by name (scoped as `pkg::module::Type`), an -array (`Message[]`, `u8[16]`) or a union (`union(string u32)`). +array (`Message[max 100]`, `u8[16]`) or a union (`union(char[max 64] u32)`). ## Docstrings and annotations @@ -53,9 +53,9 @@ do. struct Message { /// Plain-text body, UTF-8. @validators = [StringBounds(min_chars = 1)] - body: string + body: char[max 4096] /// Shown in the client's list view. - optional subject: string + optional subject: char[max 128] } ``` diff --git a/docs/docs/guide/idl/types.md b/docs/docs/guide/idl/types.md index 5fb1608..ec59c94 100644 --- a/docs/docs/guide/idl/types.md +++ b/docs/docs/guide/idl/types.md @@ -8,27 +8,119 @@ Primitives: | unsigned integers | `u8` `u16` `u32` `u64` `u128` | | floats | `f32` `f64` | | boolean | `bool` | -| text | `string` (see below) | +| text | `string`, `char` (see below) | -Plus any `struct` / `enum` name (scoped: `pkg::module::Type`), arrays (`Type[]` -or fixed `Type[10]`), and unions (`union(TypeA TypeB)`). +Plus any `struct` / `enum` name (scoped: `pkg::module::Type`), arrays (`Type[]`, +`Type[max 100]` or fixed `Type[10]`), and unions (`union(TypeA TypeB)`). -### Text: `string` +Every string and every dynamic array needs a [maximum](#bounds), written in its +type or given by a [setting](settings.md#default-maximums). The examples in this guide +carry maxima so they build as written; a bare `string` or `T[]` in one of your +schemas builds only once a default is set. -- **`string`** is the text type: UTF-8, any length. +### Text: `string` and `char` + +- **`char`** is one Unicode scalar value: a single character, not a byte or a + UTF-16 unit. Its literal is a string of exactly one character, `"a"`; any + other length is a build error. +- **`string`** is the text type: UTF-8, the built-in name for `char[]`. An + array of `char` is always text, so `char[max 64]` is a string of at most 64 + characters, not a list of 64 `char` values. - **`str`** was an accepted spelling until it was removed. Writing it is now a build error that tells you to use `string`. - **`String`** (capitalised) is **not** Comline syntax. It is the Rust type that `string` generates into, so you see it in generated Rust, never in a `.ids` file. Writing it gets the same hint. +## Bounds + +A **maximum** says how big a value may be, in its type, so a decoder can refuse +an oversized value before it allocates one. It is written `max N` inside the +brackets, and counts items, or characters for a string: + +```ids +struct Customer { + name: char[max 32] // a string of at most 32 characters + code: char[8] // a string of exactly 8 characters + orders: Order[max 100] // at most 100 orders + tags: char[max 32][max 10] // at most 10 tags, each at most 32 characters + ids: u64[16] // exactly 16 (a fixed array, as always) +} +``` + +- **`T[N]`** is exactly `N`. **`T[max N]`** is at most `N`. `T[]` writes no + maximum, and needs one from a setting. +- **Only a maximum.** A minimum ("not empty", "at least one") is a + [validator](validator.md#the-standard-validators): `NonEmpty`, `MinChars`, + `MinItems`. So is a range of values, `IntRange`. +- **`N` is an integer or a [constant](const.md#sizes-from-constants):** + `char[max NAME_MAX]`. It is at least 1 and at most `u32::MAX` (4294967295); + `max 0`, an exact length of 0 and a negative size are build errors. +- **`max` is a keyword only right after `[`.** Anywhere else it is an ordinary + name, so a field called `max` is fine. +- **Only strings and dynamic arrays take one.** Integers, floats, `bool`, enums, + structs, unions and `()` don't. `string[max 10]` is ten strings, each at the + package default; for a bounded string write `char[max N]`. +- **Any change to a maximum is breaking**: tightening breaks old senders and + loosening breaks old receivers. + +### Every string and list has a maximum + +A schema builds only when every string and dynamic array, at every position +(field, argument, return, alias, union member), has a maximum, from the first of: + +1. the position itself, `char[max 64]`; +2. a [default from settings](settings.md#default-maximums), `bounds.string.max` + for strings and `bounds.array.max` for lists, stored resolved at each + position it reaches; +3. a give-up: [`@unverified`](protocol.md#giving-up-a-guarantee) on every + protocol that reaches the position, which gives up bounded size. + +There is no built-in default, so a position with none of these is an error that +names it and the fix: + +``` +struct `Greeting`, field `message`: `string` has no maximum + Help: write `char[max N]`, or set `bounds.string.max` in settings +``` + +A position no protocol reaches, such as a type another package can use, has to +be bounded. A struct that can contain itself also needs a +[depth limit](annotations.md#max_depth). + +A package default reaches only its own positions: a dependency's types keep +the maxima resolved in the dependency. + +### Using a bounded alias + +A [type alias](#type-aliases) carries its bound, and the limit is changed +there. Where an alias of a string or of a dynamic array is used (a field, +argument, return or union member), it takes **no `[…]` suffix** of its own: + +```ids +type Name = char[max 32] +type Names = Name[max 10] // a list of an alias is its own alias + +struct Customer { + name: Name // fine + nicknames: Names // fine + others: Name[max 5] // error: `Name` is an alias of a string, which + // takes no `[…]` where it's used +} +``` + +The error suggests the alias to declare instead. The rule covers aliases of +strings and dynamic arrays; an alias of a number or a struct keeps the suffix +(`UserId[max 10]`), and the built-in `string` is exempt (`string[max 10]`). +Writing an alias in a list inside another alias, as `Names` does, is allowed. + ## Type aliases `type NAME = TYPE` gives a type a second name: ```ids type UserId = u64 -type Handle = string +type Handle = char[max 32] struct User { id: UserId @@ -53,13 +145,21 @@ check every value of it, and `@deprecated`, which warns wherever it's used. | `u64`, `u128` | `u64`, `u128` | `bigint` | | `f32` / `f64` | `f32` / `f64` | `number` | | `bool` | `bool` | `boolean` | -| `string` | `String` | `string` | +| `string`, `char[max N]` | `String` | `string` | +| `char` | not supported yet | not supported yet | | `Message` | `Message` | `Message` | | `Message[]` | `Vec` | `Message[]` | | `u8[16]` | `[u8; 16]` | `number[]` | | `union(string u32)` | not supported yet | `string \| number` | | `optional x: T` | `Option` | `x?: T` | +A maximum is in the stored schema and part of a package's version, but +generated code doesn't enforce it yet: a bounded string is a `String` or +`string`, and a bounded list a `Vec` or an array. Checks while decoding and +encoding come with the runtimes, and both generators refuse a single `char` +until a wire format carries one. Each generator's state is on the +[language support](../../reference/languages/index.md) page. + TypeScript's `number` holds integers exactly only up to 2^53, so the 64- and 128-bit integers are `bigint` there, in generated types and in both codecs. diff --git a/docs/docs/guide/idl/use.md b/docs/docs/guide/idl/use.md index 7d9134e..abadf95 100644 --- a/docs/docs/guide/idl/use.md +++ b/docs/docs/guide/idl/use.md @@ -83,17 +83,19 @@ in `config.idp`, and the editor and the playground know it too. | Schema | Declares | |---|---| -| `std::http` | `HttpMethod` (enum: `GET`, `POST`, `PUT`, `DELETE`), `Request` (`method`, `uri`), `Response` (`status_code`) | -| `std::validators` | `StringBounds`, a validator with `min_chars` and `max_chars` | +| `std::http` | `HttpMethod` (enum: `GET`, `POST`, `PUT`, `DELETE`), `Request` (`method`, `uri`: at most 8192 characters), `Response` (`status_code`) | +| `std::validators` | the [validators](validator.md#the-standard-validators) `NonEmpty`, `MinChars`, `MinItems`, `IntRange` and `StringBounds` | ```ids use std::http::Request -use std::validators::StringBounds +use std::validators::{NonEmpty, MinChars} struct Call { request: Request - @validators = [StringBounds(min_chars = 1, max_chars = 64)] - label: string + @validators = [MinChars(min = 1)] + label: char[max 64] + @validators = [NonEmpty] + tags: char[max 16][max 8] } ``` diff --git a/docs/docs/guide/idl/validator.md b/docs/docs/guide/idl/validator.md index 937f196..b551d12 100644 --- a/docs/docs/guide/idl/validator.md +++ b/docs/docs/guide/idl/validator.md @@ -19,7 +19,7 @@ A **validator** is a named, parameterised check you attach to a /// @max_chars: maximum length validator StringBounds for string { min_chars: u32 = 0 - max_chars: u32 = 1024 + max_chars: u32 = u32::MAX validate { assert(value.length >= params.min_chars, @@ -48,7 +48,15 @@ validator Range for u8, u16, u32 { … } - On an array field, a validator checks the **array**, not each element: a `for string` validator doesn't go on a `string[]` field. - Targets are primitives, arrays of them, or aliases. There are no generic - targets; list each type instead. + targets; list each type instead, with one exception: `any[]`. +- **Bounds are ignored when matching.** `for string` applies to every string, + whatever its maximum (`char[max 32]`, `char[8]`), and `for u32[]` to every + `u32[max N]`. +- **`any[]`** is a dynamic array of any element type, so one validator can check + a list's length without naming what it holds. `any` is a keyword only as an + array's element in a `for`: `any[][]` is a list of lists, and a bare `any` + is an error. `any[]` doesn't match a string, which is why std's `NonEmpty` + lists both: `for string, any[]`. ## Properties @@ -97,7 +105,7 @@ that bind the validator's properties by name. ```ids linenums="1" struct Message { @validators = [StringBounds(min_chars = 3, max_chars = 12)] - recipient: string + recipient: char[max 64] } ``` @@ -115,6 +123,41 @@ local one: its `for` targets and its arguments, against its declaration. `@validators` goes on a field or a `type` alias. On a struct, error, protocol or function there's no single value for it to check, so it's a build error. +## The standard validators + +[`std::validators`](../../std/validators.md) ships these. A **maximum** belongs +in the type ([`char[max 32]`](types.md#bounds)), where a decoder checks it before +allocating; validators check what a type can't say, a minimum or a range. + +| Validator | For | Checks | +|---|---|---| +| `NonEmpty` | `string`, `any[]` | not empty | +| `MinChars(min)` | `string` | at least `min` characters | +| `MinItems(min)` | `any[]` | at least `min` items | +| `IntRange(min, max)` | `u8` `u16` `u32` `u64` `s8` `s16` `s32` `s64` | the value is within `min` and `max`, both included; each defaults to the type's widest bound | +| `StringBounds(min_chars, max_chars)` | `string` | the length is within both; `max_chars` defaults to no limit. Prefer the type's maximum and `MinChars` | + +```ids linenums="1" +use std::validators::{NonEmpty, MinItems, IntRange} + +struct Customer { + @validators = [NonEmpty] + name: char[max 32] + + @validators = [MinItems(min = 1)] + orders: Order[max 100] + + @validators = [IntRange(min = 1, max = 12)] + month: u8 +} +``` + +A std validator's size is checked against the type's maximum at build. A +minimum above it refuses every value, so it is an error: `MinChars(min = 40)` +on a `char[max 32]` (`bounds::validator-minimum-above-maximum`). A cap below it +refuses values the type allows, so it is a warning that suggests moving the cap +into the type (`bounds::validator-caps-below-type`). + ## On a type alias Put `@validators` on a `type` alias to check every value of that alias, @@ -124,11 +167,12 @@ wherever it's used: use std::validators::StringBounds @validators = [StringBounds(min_chars = 2, max_chars = 8)] -type Handle = string +type Handle = char[max 32] +type Handles = Handle[max 20] struct Account { handle: Handle - friends: Handle[] + friends: Handles } protocol Accounts { @@ -151,7 +195,7 @@ an alias: innermost first), then by the field's own. - The validator's `for` target is checked once, against what the alias resolves to. - An alias of an alias collects the checks along the chain. -- An array of the alias (`Handle[]`) checks each element. +- A list of the alias (`Handles`, above) checks each element. - An alias is the only way to check a **function argument**: arguments take no annotations of their own, but `to: Handle` runs `Handle`'s checks. diff --git a/docs/docs/proposals/index.md b/docs/docs/proposals/index.md index 204c451..1ab9a51 100755 --- a/docs/docs/proposals/index.md +++ b/docs/docs/proposals/index.md @@ -191,10 +191,12 @@ Whether "one of several shapes, with a tag" is a feature of `enum` or of #### [Bounds on types](type-bounds/index.md) -How a size limit is written on a type (`T[1..10]`, a string of at most 64 +How a size limit is written on a type (`Order[max 100]`, a string of at most 64 characters), what a string bound counts, and which types take one. Four competing proposals, ***decided: D*** (2026-11-02; the -[Design record](../design/type-bounds.md)): +[Design record](../design/type-bounds.md), [core#98](https://github.com/ComlineProject/core/issues/98); +the language side is shipped and documented in the +[guide](../guide/idl/types.md#bounds), the runtimes' checks are next): - [How bounds work](type-bounds/model.md): which types take a bound, where it can be written, where it comes from, and what each part of Comline does with diff --git a/docs/docs/proposals/type-bounds/index.md b/docs/docs/proposals/type-bounds/index.md index 36a2a7e..0c771f9 100644 --- a/docs/docs/proposals/type-bounds/index.md +++ b/docs/docs/proposals/type-bounds/index.md @@ -133,9 +133,11 @@ bound. [How bounds work](model.md) has the full model: each type and why, every position a bound can be written in, where a bound comes from (written, through an alias, a constant, a default), and what the build, version comparison, generated code, decoders and the language server each do with it. This section is the short version. -Not settled. core#98 names arrays and strings, and its reason, refusing an -oversized value before allocating, only covers types whose size varies. A -bound could mean two different things: +**Decided 2026-11-02: size bounds only, on strings and dynamic arrays** (rule 1 +below); integer ranges stay with validators (`IntRange`). What follows is the +comparison that led there. core#98 names arrays and strings, and its reason, +refusing an oversized value before allocating, only covers types whose size +varies. A bound could mean two different things: - **A size bound:** how big a value may be (characters, items). It protects decoders and can change the generated type (a fixed-capacity string). @@ -261,13 +263,13 @@ encoded differently from `string`. ([issue 3](max-only.md#issues-and-resolutions)). - **An exact length:** `8..8` only, or a shorthand. A shorthand like `string(8)` reads too much like the fixed array `f32[3]`. -- **Which types take a bound:** size bounds only (strings, arrays), or range - bounds on scalars too. See [Which types take a bound](#which-types-take-a-bound). - Under D, only maximums on strings and arrays. +- ~~**Which types take a bound**~~: decided, size bounds only: maximums on + strings and dynamic arrays. See [Which types take a bound](#which-types-take-a-bound). - **Under D, the cost of minimums as validators:** an extra pass per string, and checks that run only when the receiver opts in ([weighed here](max-only.md#what-a-validator-minimum-costs)). Unmeasured. - ~~**Under D, a string's own maximum**~~: decided, `char[max 64]`, replacing the earlier `string(max 64)` ([why](char-strings.md)). -- **Under D, minimum validators std would need:** `NonEmpty`, and `IntRange` for - integer value ranges. +- ~~**Under D, minimum validators std would need**~~: shipped in std, + `NonEmpty`, `MinChars`, `MinItems` and `IntRange` + ([the guide](../../guide/idl/validator.md#the-standard-validators)). diff --git a/docs/docs/reference/languages/index.md b/docs/docs/reference/languages/index.md index d6b7c27..162eee9 100644 --- a/docs/docs/reference/languages/index.md +++ b/docs/docs/reference/languages/index.md @@ -93,6 +93,8 @@ commit. A runtime's suite runs every example against it: | the `packed@1` format
`format-packed` | ✅ supported | ✅ supported | | the `json@1` format
`format-json` | ✅ supported | ✅ supported | | the `msgpack@1` format
`format-msgpack` | ✅ supported | ❌ unsupported: `@comline/runtime` has no MessagePack codec yet | +| bounds
`bounds` | ⚪ ignored: a bounded string is a `String` and a bounded list a `Vec`; nothing checks the maximum yet ([core#98](https://github.com/ComlineProject/core/issues/98)) | ⚪ ignored: a bounded string is a `string` and a bounded list an array; nothing checks the maximum yet ([core#98](https://github.com/ComlineProject/core/issues/98)) | +| single characters
`chars` | ❌ unsupported: no wire format carries a single `char` yet ([core#98](https://github.com/ComlineProject/core/issues/98)) | ❌ unsupported: no wire format carries a single `char` yet ([core#98](https://github.com/ComlineProject/core/issues/98)) | diff --git a/docs/docs/reference/languages/rust.md b/docs/docs/reference/languages/rust.md index 05cb080..fb6b9f8 100644 --- a/docs/docs/reference/languages/rust.md +++ b/docs/docs/reference/languages/rust.md @@ -16,14 +16,14 @@ Generator `rust#1.85.0`. | Feature | What it covers | State | Proven by | |---|---|---|---| -| structs
`structs` | `struct` declarations | ✅ supported | `primitives`, `optional_and_arrays`, `type_refs`, `protocol`, `shapes`, `cross_schema`, `import_alias`, `import_glob`, `nested_namespace`, `external_std`, `validators`, `validators_on_decode`, `format_json`, `format_msgpack` | +| structs
`structs` | `struct` declarations | ✅ supported | `primitives`, `optional_and_arrays`, `type_refs`, `protocol`, `shapes`, `cross_schema`, `import_alias`, `import_glob`, `nested_namespace`, `external_std`, `validators`, `validators_on_decode`, `format_json`, `format_msgpack`, `bounds` | | enums
`enums` | `enum` declarations | ✅ supported | `enum_basic` | -| optional fields
`optional-fields` | fields marked `optional` | ✅ supported | `optional_and_arrays`, `type_refs`, `shapes`, `cross_schema`, `validators`, `validators_on_decode` | -| arrays
`arrays` | variable-length arrays, `T[]` | ✅ supported | `optional_and_arrays`, `type_refs`, `shapes`, `cross_schema`, `validators`, `validators_on_decode` | +| optional fields
`optional-fields` | fields marked `optional` | ✅ supported | `optional_and_arrays`, `type_refs`, `shapes`, `cross_schema`, `validators`, `validators_on_decode`, `bounds` | +| arrays
`arrays` | variable-length arrays, `T[]` | ✅ supported | `optional_and_arrays`, `type_refs`, `shapes`, `cross_schema`, `validators`, `validators_on_decode`, `bounds` | | fixed-length arrays
`fixed-arrays` | fixed-length arrays, `T[N]` | ✅ supported | `shapes` | | fixed arrays over 32 elements, nested
`large-fixed-arrays-nested` | a `T[N]` with N over 32 anywhere but a field's own, non-optional type: inside another array, optional, an alias, an argument or a return | ❌ unsupported: a fixed array over 32 elements renders only as a struct or error field's own, non-optional type (serde's derive stops at 32) | `large_fixed_arrays_nested` | | unions
`unions` | `union(A B ...)` types | ❌ unsupported: Rust has no anonymous sum type to render one as | `unions` | -| type aliases
`type-aliases` | `type Name = ...` declarations | ✅ supported | `validators`, `validators_on_decode` | +| type aliases
`type-aliases` | `type Name = ...` declarations | ✅ supported | `validators`, `validators_on_decode`, `bounds` | | constants
`constants` | `const` declarations | ✅ supported | `constant`, `shapes`, `validators`, `validators_on_decode` | | protocols
`protocols` | `protocol` declarations and their functions | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `framing_jsonrpc`, `handshake_none`, `connections`, `connections_async`, `connections_jsonrpc`, `format_json`, `format_msgpack` | | errors
`errors` | `error` declarations | ✅ supported | `protocol`, `error_shapes`, `format_json`, `format_msgpack` | @@ -41,6 +41,8 @@ Generator `rust#1.85.0`. | the `packed@1` format
`format-packed` | `wire.format = "packed@1"`, the default: fixed-width fields, no tags | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `connections`, `connections_async` | | the `json@1` format
`format-json` | `wire.format = "json@1"` | ✅ supported | `format_json` | | the `msgpack@1` format
`format-msgpack` | `wire.format = "msgpack@1"` | ✅ supported | `format_msgpack` | +| bounds
`bounds` | a maximum or exact length on a string or list (`char[max 64]`, `char[8]`, `T[max N]`), or a depth limit (`@max_depth`): checked while decoding and encoding | ⚪ ignored: a bounded string is a `String` and a bounded list a `Vec`; nothing checks the maximum yet ([core#98](https://github.com/ComlineProject/core/issues/98)) | `bounds` | +| single characters
`chars` | `char`: one Unicode scalar value | ❌ unsupported: no wire format carries a single `char` yet ([core#98](https://github.com/ComlineProject/core/issues/98)) | `chars` | @@ -59,14 +61,14 @@ Runtime `rust`. | Feature | What it covers | State | Proven by | |---|---|---|---| | name hash
`name-hash` | FNV-1a 64 of a wire format or framing name, as the handshake carries it | ✅ supported | [8 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/name-hash.json) | -| handshake
`handshake` | the fixed 31-byte frame each side sends first: magic, version, IR hash, wire format, framing, capabilities | ✅ supported | [9 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/handshake.json) | +| handshake
`handshake` | the fixed 31-byte frame each side sends first: magic, version, IR hash, wire format, framing, capabilities | ✅ supported | [13 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/handshake.json) | | envelope
`envelope` | a response's outcome: ok with a payload, an error ordinal with its body, or a provider fault | ✅ supported | [8 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/envelope.json) | | datagram framing
`framing-datagram` | Comline's own binary framing of requests and responses | ✅ supported | [9 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-datagram.json) | | datagram@2 framing
`framing-datagram2` | the datagram framing with a request/reply kind and a protocol number, for calls in both directions and several protocols on one connection | ✅ supported | [12 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-datagram2.json) | | stream framing
`stream` | frames on a byte stream (TCP, a pipe): each behind a u32 little-endian length prefix, refused over the limit, by default 16 MiB (16777216 bytes) in every runtime | ✅ supported | [24 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/stream.json) | -| JSON-RPC framing
`framing-jsonrpc` | JSON-RPC 2.0 requests and responses, a fault as -32603 | ✅ supported | [19 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-jsonrpc.json) | -| JSON wire format
`format-json` | values as UTF-8 JSON: a struct as an object | ✅ supported | [46 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/format-json.json) | -| MessagePack wire format
`format-msgpack` | values as MessagePack: a struct as an array | ✅ supported | [45 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/format-msgpack.json) | +| JSON-RPC framing
`framing-jsonrpc` | JSON-RPC 2.0 requests and responses, a fault as -32603 | ✅ supported | [26 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-jsonrpc.json) | +| JSON wire format
`format-json` | values as UTF-8 JSON: a struct as an object | ✅ supported | [48 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/format-json.json) | +| MessagePack wire format
`format-msgpack` | values as MessagePack: a struct as an array | ✅ supported | [48 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/format-msgpack.json) | | packed wire format
`format-packed` | values as packed@1: fixed-width fields back to back, varint lengths, no tags | ✅ supported | [59 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/format-packed.json) | diff --git a/docs/docs/reference/languages/typescript.md b/docs/docs/reference/languages/typescript.md index 36fe672..c840627 100644 --- a/docs/docs/reference/languages/typescript.md +++ b/docs/docs/reference/languages/typescript.md @@ -16,14 +16,14 @@ Generator `typescript#5.0`. | Feature | What it covers | State | Proven by | |---|---|---|---| -| structs
`structs` | `struct` declarations | ✅ supported | `primitives`, `optional_and_arrays`, `type_refs`, `protocol`, `shapes`, `cross_schema`, `import_alias`, `import_glob`, `nested_namespace`, `external_std`, `validators`, `validators_on_decode`, `unions`, `large_fixed_arrays_nested`, `format_json` | +| structs
`structs` | `struct` declarations | ✅ supported | `primitives`, `optional_and_arrays`, `type_refs`, `protocol`, `shapes`, `cross_schema`, `import_alias`, `import_glob`, `nested_namespace`, `external_std`, `validators`, `validators_on_decode`, `unions`, `large_fixed_arrays_nested`, `format_json`, `bounds` | | enums
`enums` | `enum` declarations | ✅ supported | `enum_basic` | -| optional fields
`optional-fields` | fields marked `optional` | ✅ supported | `optional_and_arrays`, `type_refs`, `shapes`, `cross_schema`, `validators`, `validators_on_decode`, `large_fixed_arrays_nested` | -| arrays
`arrays` | variable-length arrays, `T[]` | ✅ supported | `optional_and_arrays`, `type_refs`, `shapes`, `cross_schema`, `validators`, `validators_on_decode`, `large_fixed_arrays_nested` | +| optional fields
`optional-fields` | fields marked `optional` | ✅ supported | `optional_and_arrays`, `type_refs`, `shapes`, `cross_schema`, `validators`, `validators_on_decode`, `large_fixed_arrays_nested`, `bounds` | +| arrays
`arrays` | variable-length arrays, `T[]` | ✅ supported | `optional_and_arrays`, `type_refs`, `shapes`, `cross_schema`, `validators`, `validators_on_decode`, `large_fixed_arrays_nested`, `bounds` | | fixed-length arrays
`fixed-arrays` | fixed-length arrays, `T[N]` | 🟡 partial: rendered as `T[]`: the length isn't part of the type | `shapes`, `large_fixed_arrays_nested` | | fixed arrays over 32 elements, nested
`large-fixed-arrays-nested` | a `T[N]` with N over 32 anywhere but a field's own, non-optional type: inside another array, optional, an alias, an argument or a return | 🟡 partial: rendered as `T[]`: the length isn't part of the type | `large_fixed_arrays_nested` | | unions
`unions` | `union(A B ...)` types | ✅ supported | `unions` | -| type aliases
`type-aliases` | `type Name = ...` declarations | ✅ supported | `validators`, `validators_on_decode`, `unions` | +| type aliases
`type-aliases` | `type Name = ...` declarations | ✅ supported | `validators`, `validators_on_decode`, `unions`, `bounds` | | constants
`constants` | `const` declarations | ✅ supported | `constant`, `shapes`, `validators`, `validators_on_decode` | | protocols
`protocols` | `protocol` declarations and their functions | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `framing_jsonrpc`, `handshake_none`, `connections`, `connections_async`, `connections_jsonrpc`, `format_json` | | errors
`errors` | `error` declarations | ✅ supported | `protocol`, `error_shapes`, `format_json` | @@ -41,6 +41,8 @@ Generator `typescript#5.0`. | the `packed@1` format
`format-packed` | `wire.format = "packed@1"`, the default: fixed-width fields, no tags | ✅ supported | `protocol`, `error_shapes`, `validators`, `validators_on_decode`, `handshake_none`, `connections`, `connections_async` | | the `json@1` format
`format-json` | `wire.format = "json@1"` | ✅ supported | `format_json` | | the `msgpack@1` format
`format-msgpack` | `wire.format = "msgpack@1"` | ❌ unsupported: `@comline/runtime` has no MessagePack codec yet | `format_msgpack` | +| bounds
`bounds` | a maximum or exact length on a string or list (`char[max 64]`, `char[8]`, `T[max N]`), or a depth limit (`@max_depth`): checked while decoding and encoding | ⚪ ignored: a bounded string is a `string` and a bounded list an array; nothing checks the maximum yet ([core#98](https://github.com/ComlineProject/core/issues/98)) | `bounds` | +| single characters
`chars` | `char`: one Unicode scalar value | ❌ unsupported: no wire format carries a single `char` yet ([core#98](https://github.com/ComlineProject/core/issues/98)) | `chars` | @@ -59,13 +61,13 @@ Runtime `typescript`. | Feature | What it covers | State | Proven by | |---|---|---|---| | name hash
`name-hash` | FNV-1a 64 of a wire format or framing name, as the handshake carries it | ✅ supported | [8 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/name-hash.json) | -| handshake
`handshake` | the fixed 31-byte frame each side sends first: magic, version, IR hash, wire format, framing, capabilities | ✅ supported | [9 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/handshake.json) | +| handshake
`handshake` | the fixed 31-byte frame each side sends first: magic, version, IR hash, wire format, framing, capabilities | ✅ supported | [13 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/handshake.json) | | envelope
`envelope` | a response's outcome: ok with a payload, an error ordinal with its body, or a provider fault | ✅ supported | [8 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/envelope.json) | | datagram framing
`framing-datagram` | Comline's own binary framing of requests and responses | ✅ supported | [9 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-datagram.json) | | datagram@2 framing
`framing-datagram2` | the datagram framing with a request/reply kind and a protocol number, for calls in both directions and several protocols on one connection | ✅ supported | [12 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-datagram2.json) | | stream framing
`stream` | frames on a byte stream (TCP, a pipe): each behind a u32 little-endian length prefix, refused over the limit, by default 16 MiB (16777216 bytes) in every runtime | ❌ unsupported: no length-prefixed framing or frame limit yet: the transports are message-oriented ([comline-typescript#80](https://github.com/ComlineProject/comline-typescript/issues/80)) | — | -| JSON-RPC framing
`framing-jsonrpc` | JSON-RPC 2.0 requests and responses, a fault as -32603 | ✅ supported | [19 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-jsonrpc.json) | -| JSON wire format
`format-json` | values as UTF-8 JSON: a struct as an object | 🟡 partial: decoding doesn't check enum variants or integer ranges ([comline-typescript#57](https://github.com/ComlineProject/comline-typescript/issues/57))
fails: `format-json/decode-unknown-variant`, `format-json/decode-wider-integer-overflow` | [44 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/format-json.json) | +| JSON-RPC framing
`framing-jsonrpc` | JSON-RPC 2.0 requests and responses, a fault as -32603 | ✅ supported | [26 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/framing-jsonrpc.json) | +| JSON wire format
`format-json` | values as UTF-8 JSON: a struct as an object | 🟡 partial: decoding doesn't check enum variants or integer ranges ([comline-typescript#57](https://github.com/ComlineProject/comline-typescript/issues/57))
fails: `format-json/decode-unknown-variant`, `format-json/decode-wider-integer-overflow` | [46 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/format-json.json) | | MessagePack wire format
`format-msgpack` | values as MessagePack: a struct as an array | ❌ unsupported: JSON and packed@1 ship | — | | packed wire format
`format-packed` | values as packed@1: fixed-width fields back to back, varint lengths, no tags | ✅ supported | [59 cases](https://github.com/ComlineProject/runtime/blob/main/runtime/conformance/vectors/format-packed.json) | diff --git a/docs/docs/reference/wire/packed.md b/docs/docs/reference/wire/packed.md index 218b776..191dda5 100644 --- a/docs/docs/reference/wire/packed.md +++ b/docs/docs/reference/wire/packed.md @@ -46,8 +46,8 @@ enum Class { struct Player { id: u32 hp: u16 - name: string - optional guild: string + name: char[max 32] + optional guild: char[max 32] class: Class pos: f32[2] }