Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/docs/design/type-bounds.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
8 changes: 7 additions & 1 deletion docs/docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
29 changes: 28 additions & 1 deletion docs/docs/guide/idl/annotations.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ protocol Mail {
function send(message: Message) -> bool;

@idempotent
function fetch_inbox() -> Message[];
function fetch_inbox() -> Message[max 100];
}
```

Expand All @@ -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) |
Expand All @@ -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
Expand Down
32 changes: 29 additions & 3 deletions docs/docs/guide/idl/const.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
2 changes: 1 addition & 1 deletion docs/docs/guide/idl/docstrings.md
Original file line number Diff line number Diff line change
Expand Up @@ -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]
}
```

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/guide/idl/error.md
Original file line number Diff line number Diff line change
Expand Up @@ -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]
}
```

Expand Down
4 changes: 2 additions & 2 deletions docs/docs/guide/idl/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
14 changes: 7 additions & 7 deletions docs/docs/guide/idl/protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -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();
}
```
Expand All @@ -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;
}
```

Expand Down Expand Up @@ -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;
}
```

Expand Down Expand Up @@ -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();
}
```
Expand Down Expand Up @@ -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();
}
```
Expand Down
61 changes: 60 additions & 1 deletion docs/docs/guide/idl/settings.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,11 +107,12 @@ are permission toggles taking a boolean (`true` / `false`):
- `<name>` 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.<name>.max` | a positive integer; see [Default maximums](#default-maximums) |
| `diagnostics."<code>".level` | one of `allow`, `hint`, `info`, `warn`, `error` |
| `mode` | the bare keyword `replace` |

Expand Down Expand Up @@ -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.<name>.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
Expand Down
18 changes: 9 additions & 9 deletions docs/docs/guide/idl/structure.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
```
Expand All @@ -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
}
Expand All @@ -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

Expand All @@ -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]
}
```
Loading
Loading