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/guides/codegen/generating-code.md
Original file line number Diff line number Diff line change
Expand Up @@ -289,7 +289,7 @@ import type { Greeting } from "./types.js";
```

An alias imports the name the other module actually exports
(`use types::Greeting as G` → `import type { Greeting as G }`), and a `use`
(`use package::types::Greeting as G` → `import type { Greeting as G }`), and a `use`
nothing refers to produces no import at all.

`std` again resolves to its own package when
Expand Down
7 changes: 4 additions & 3 deletions docs/docs/guides/idl/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,10 +58,11 @@ next declaration. `//!` lines at the top of a file are its

```ids title="imports.ids"
use std::http::Request
use mypackage::{User, Post}
use package::types::{User, Post}
use external::uuid::Uuid as UUID
use parent::common::*
```

`self::`, `parent::` and `package::` prefixes resolve relative to the current
schema. See [Imports](use.md).
A package's own schemas are reached only through `package::`, `parent::` and
`self::`, which resolve relative to the current schema; any other path means
`std` or a dependency. See [Imports](use.md).
97 changes: 79 additions & 18 deletions docs/docs/guides/idl/use.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,44 +5,100 @@ current file.

```ids
use std::http::Request
use mypackage::types::User
use mypackage::{User, Post, Comment}
use mypackage::utils::*
use package::types::User
use package::types::{User, Post, Comment}
use package::utils::*
use external::uuid::Uuid as UUID
use parent::common::Error
```

## Which path reaches what

A package's **own schemas are reached only through a relative path**: `package::`,
`parent::` or `self::`. A path that starts with anything else is
**absolute**, and an absolute path always means `std` or a dependency, never the
package itself.

| To reach | Write |
|---|---|
| a schema of this package, from its root | `use package::types::User` |
| the schema one level up | `use parent::common::Error` |
| the current schema, and what is under it | `use self::nested::Type` |
| a dependency | `use greeting::hello::Greeting` |
| the standard library | `use std::http::Request` |

`std`, `package`, `parent` and `self` are reserved: none can be the name of a
dependency, so the four are the only first segments that aren't a
dependency's. `package::` is the same wherever the file sits, so moving a schema
to another directory doesn't change what its imports say.

## Path forms

| Form | Example | Brings in |
|---|---|---|
| absolute | `use pkg::module::Type` | one item by its full path |
| whole namespace | `use pkg::module` | everything in that module, bare or qualified (`Type` or `pkg::module::Type`) |
| multi | `use pkg::module::{A, B, C}` | several items from one module (plain names, no nesting or `as` inside the braces) |
| glob | `use pkg::module::*` | everything in that module |
| single item | `use package::module::Type` | one item by its full path |
| whole namespace | `use package::module` | everything in that module, bare or qualified (`Type` or `module::Type`) |
| multi | `use package::module::{A, B, C}` | several items from one module (plain names, no nesting or `as` inside the braces) |
| glob | `use package::module::*` | everything in that module |
| relative | `use parent::common::Error`, `use self::nested::Type`, `use package::types::User` | resolved against the current schema: `parent::` is one level up, `self::` the schema itself (`self::nested` is a schema under it), `package::` the package root |

The first four rows show `package::`; a dependency's or `std`'s schema takes the
same forms with its own name first (`use greeting::hello::{A, B}`,
`use std::http::*`).

A relative prefix works in every form, including a glob or `{ ... }` straight
after it: `use parent::*` and `use parent::{Error, Page}` import from the schema
one level up (`api.ids`, for a file `api/v1.ids`), and `use parent::common::*`
from the `common` schema beside it. As with any path, one that names no schema,
or an item the schema doesn't declare, fails the build
([below](#when-nothing-matches)).

### A bare path to your own schema is an error

Writing a package's own schema without a relative prefix, in any form (a single
item, a whole namespace, `{ ... }` or `*`, with or without `as`), is an error at
once:

```ids
use types::{User, Post}
```

The build reports it as `import::bare-own-schema-path`, with:

- **message:** `'types::{User, Post}' is one of this package's own schemas, reached by a bare path`
- **context:** ``an absolute path starts with `std` or a dependency's name; 'types' is neither``
- **help:** ``write `package::types::{User, Post}`: a package's own schemas are reached as `package::...`, `parent::...` or `self::...` ``

`comline check` and `comline build` fail on it. The diagnostic carries a quick
fix, titled ``Write `package::types::{User, Post}` ``, that inserts `package::` at
the start of the path. The language server doesn't offer it yet
([language-server#122](https://github.com/ComlineProject/language-server/issues/122)),
and `comline fix` doesn't apply it across a package yet
([cli#162](https://github.com/ComlineProject/cli/issues/162)). Qualified
references the import brought in don't change: they're written with the
schema's namespace (`types::User`) whichever path reached it. A path whose first segment is neither `std`, a
dependency nor one of the package's own schemas is not this error but a
[path that matches nothing](#when-nothing-matches).

## Referring to what you imported

After a `use`, a type can be written **bare** or **qualified**, Rust-style:
After a `use`, a type can be written **bare** or **qualified**, Rust-style. The
qualified path is the schema's own namespace (`types::User`), not the path the
`use` was written with:

| statement | write the type as |
|---|---|
| `use pkg::types::User` | `User` **or** `pkg::types::User` |
| `use pkg::types::{User, Post}` | `User` / `Post`, or the qualified path |
| `use pkg::types::*` | any name from `types`, bare or qualified |
| `use pkg::types` | `User` **or** `pkg::types::User` |
| `use pkg::types::User as Account` | `Account` **or** `pkg::types::User` — **not** bare `User` |
| `use package::types::User` | `User` **or** `types::User` |
| `use package::types::{User, Post}` | `User` / `Post`, or the qualified path |
| `use package::types::*` | any name from `types`, bare or qualified |
| `use package::types` | `User` **or** `types::User` |
| `use package::types::User as Account` | `Account` **or** `types::User` — **not** bare `User` |

A dependency's schema is qualified by its own path the same way
(`use greeting::hello::Greeting` brings `greeting::hello::Greeting`).

A `use` never shadows a declaration in the current file: a local `struct User`
always wins over `use other::User`.
always wins over `use package::other::User`.

## Alias

Expand All @@ -68,11 +124,16 @@ closest match when there is one:

| `use` | Error |
|---|---|
| `use typse::User` (no schema `typse`) | `no schema in this package or its dependencies matches 'typse::User' - did you mean 'types'?` |
| `use types::Usr` (`types` has no `Usr`) | `schema 'types' doesn't declare 'Usr' - did you mean 'User'?` |
| `use typse::User` (no schema `typse`, in the package or its dependencies) | `no schema in this package or its dependencies matches 'typse::User' - did you mean 'types'?` |
| `use package::types::Usr` (`types` has no `Usr`) | `schema 'types' doesn't declare 'Usr' - did you mean 'User'?` |

Both are `import::unresolved`. `use types::User`, with `types` one of the
package's own schemas, isn't one of them: it's the
[bare own-schema path](#a-bare-path-to-your-own-schema-is-an-error) error, which
says to write `package::types::User`.

The editor reports the same errors as you type, with a quick fix to the closest
name. A `std::` path is checked the same way, against the
The editor reports the same unresolved-path errors as you type, with a quick fix
to the closest name. A `std::` path is checked the same way, against the
[standard library](#the-standard-library):
`std has no schema matching 'std::htp::Request' - did you mean 'std::http'?`

Expand Down
85 changes: 74 additions & 11 deletions docs/docs/languages/rust/client-and-server.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
# Client & server

A protocol on the lockstep `datagram` framing gets a client and a server: the
client sends a request and reads the next frame as its reply, one protocol per
transport. Every other protocol runs on a [connection](connections.md), the
default. This page assumes a schema like [Protocols](../../guides/idl/protocol.md)'s
# Lockstep `datagram`: client & server

A protocol on the lockstep `datagram` framing (`@framing = "datagram"`) gets a
client and a server: the client sends a request and reads the next frame as its
reply, one protocol per transport. This page is only that case. Every other
protocol runs on a [connection](connections.md), the default, with its own
`serve` and `connect`; [What you use](index.md#what-you-use) says which is
which. This page assumes a schema like [Protocols](../../guides/idl/protocol.md)'s
`Mail` example has been generated to Rust:

```ids
Expand All @@ -19,19 +21,70 @@ protocol Mail {

Full details are [Code generation](../../guides/codegen/index.md)'s job, not
this page's — but the shapes below are what the generated file actually
contains, so the rest of this page can refer to them by name:
contains, so the rest of this page can refer to them by name. A lockstep
protocol's file has no entry-point header; in `lib` mode the crate root's docs list it
with the `serve` and `connect` to use.

```rust
/// Canonical digest of the frozen IR this file was generated from — the
/// two ends of a connection must agree on it, and the handshake checks.
pub const IR_HASH: u64 = 0x7ea94b595fcf4393;

/// The package's wire format (`wire.format`): what this file's helpers
/// encode with, and what the peer has to speak too.
pub type Format = comline_runtime::format::Packed;

#[doc(hidden)]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MailSendMessageParams {
pub message: Message,
}

pub trait Mail {
fn send_message(&self, message: Message) -> Result<String, Fault<MailSendMessageError>>;
fn fetch_inbox(&self) -> Result<Vec<Message>, Fault<MailFetchInboxError>>;
}

pub struct MailDispatcher<S>(pub S); // implements `comline_runtime::contract::Dispatch`
#[doc(hidden)]
pub const MAIL_CALLS: &[&str] = &["send_message", "fetch_inbox"];

pub struct MailDispatcher<S>(pub S);

impl<S: Mail> Dispatch for MailDispatcher<S> { /* … */ }

impl<S: Mail> MailDispatcher<S> {
pub fn serve<T: Transport>(self, transport: &mut T) -> Result<(), RuntimeError> {
self.serve_with_format(transport, Format::default())
}

pub fn serve_with_format<T: Transport, W: WireFormat>(self, transport: &mut T, format: W)
-> Result<(), RuntimeError> {
Server::new(self, format).serve(transport, IR_HASH)
}
}

pub struct MailClient<T, W>(pub Client<T, W>);

pub const IR_HASH: u64 = 0x…; // schema fingerprint, used in the handshake
pub type Format = comline_runtime::format::Packed; // the package's wire format
impl<T: Transport, W: WireFormat> MailClient<T, W> {
pub fn new(client: Client<T, W>) -> Self { /* … */ }

pub fn connect_with_format(transport: T, format: W) -> Result<Self, RuntimeError> {
Ok(Self(Client::connect(transport, format, IR_HASH)?))
}

pub fn send_message(&mut self, message: Message) -> Result<String, CallError<MailSendMessageError>> {
let (reply, fmt) = self.0.call_with_timeout(Call::new(0, "send_message"), &MailSendMessageParams { message }, core::time::Duration::from_millis(1000))?;
// …
}

pub fn fetch_inbox(&mut self) -> Result<Vec<Message>, CallError<MailFetchInboxError>> { /* … */ }
}

impl<T: Transport> MailClient<T, Format> {
pub fn connect(transport: T) -> Result<Self, RuntimeError> {
Self::connect_with_format(transport, Format::default())
}
}
```

- `Mail` is the trait your implementation fills in — plain `&self`, a
Expand All @@ -41,9 +94,19 @@ pub type Format = comline_runtime::format::Packed; // the package's wire format
thing the schema does — it cannot raise. See
[Error handling](#error-handling-two-layers) for the `Fault` wrapper.
- `MailDispatcher<S>` wraps any `S: Mail` and implements the runtime's
`Dispatch` trait — the thing a `Server` actually drives.
`Dispatch` trait — the thing a `Server` actually drives. Its `serve` is the
one call you make to serve.
- `MailClient<T, W>` wraps a `comline_runtime::client::Client<T, W>` and
gives you one method per function, already returning the right types.
`connect` is on `MailClient<T, Format>`, so it encodes with the package's
format; `connect_with_format` takes another.
- `IR_HASH` and `Format` are defined in this file. A package that also has a
[connection](connections.md) defines `Format` once, in `connection.rs`, and
re-exports it here.
- The plumbing is `pub`, so it's there if you wire a `Client` and `Server` by
hand, and `#[doc(hidden)]`, so it isn't in rustdoc: the `…Params` structs and
the `…_CALLS` table. What's left is the trait, the dispatcher, the client and
their error types.

## Transports today

Expand Down
Loading
Loading