Skip to content

Fix Ice TODOs, update docs.zeroc.com references #474

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bernardnormier merged 7 commits into from
Apr 14, 2026
Merged

Fix Ice TODOs, update docs.zeroc.com references #474

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
7fa1acd
Fix Ice TODOs, update docs.zeroc.com references
bernardnormier Apr 13, 2026
3ac7a30
Small fix
bernardnormier Apr 13, 2026
360c24c
Potential fix for pull request finding
bernardnormier Apr 14, 2026
1ff9c09
Potential fix for pull request finding
bernardnormier Apr 14, 2026
3ae58d2
Fix more review comments
bernardnormier Apr 14, 2026
64d9ad7
Potential fix for pull request finding
bernardnormier Apr 14, 2026
e0ecf80
Fix tables
bernardnormier Apr 14, 2026
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
5 changes: 3 additions & 2 deletions content/icerpc-for-ice-users/ice-definitions/struct-types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,8 @@ encodes the struct fields with an [IceEncoder].

## cs:readonly metadata directive

You can map an Ice struct to a readonly C# struct with the `"cs:readonly"`[cs-readonly] metadata directive. For example:
You can map an Ice struct to a readonly C# struct with the [`"cs:readonly"`][cs-readonly] metadata directive. For
example:

{% aside alignment="top" %}

Expand All @@ -79,4 +80,4 @@ public readonly partial record struct Point

[IceDecoder]: csharp:IceRpc.Ice.Codec.IceDecoder
[IceEncoder]: csharp:IceRpc.Ice.Codec.IceEncoder
[cs-readonly]: TODO
[cs-readonly]: https://docs.zeroc.com/ice/3.8/csharp/slice-metadata-directives#SliceMetadataDirectives-cs:readonly
Comment thread
bernardnormier marked this conversation as resolved.
155 changes: 119 additions & 36 deletions content/icerpc/ice-protocol/protocol-frames.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ description: Understand how requests and responses are sent over ice.
## Ice interop

This section describes the ice protocol as implemented by IceRPC. The ice protocol as implemented by Ice is described
in the [Ice Manual][protocol-and-encoding], where it's known as version 1.0 of the Ice protocol.
in the [Ice Manual][ice-protocol], where it's known as version 1.0 of the Ice protocol.

Both implementations are naturally compatible to allow Ice and IceRPC applications to communicate with each others.
Both implementations are naturally compatible to allow Ice and IceRPC applications to communicate with each other.

The ice protocol implementation provided by IceRPC does not support a few non-essential features that Ice supports,
namely:
Expand All @@ -24,11 +24,32 @@ The ice protocol sends requests, responses and other information over a duplex c
All ice protocol frames have the same layout: a header followed by a body. The format of the body depends on the frame
type.

Frames and types from this page are defined using [Slice].

The header is a compact struct defined as follows:

TODO: ice definitions
Frames and types from this page are defined using [Ice's interface definition language][ice-slice].

The header is an Ice struct defined as follows:

```ice
enum FrameType
{
Request = 0,
RequestBatch = 1,
Reply = 2,
ValidateConnection = 3,
CloseConnection = 4,
Comment on lines +34 to +38
Copy link
Copy Markdown
Member Author

@bernardnormier bernardnormier Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See above

}

struct HeaderData
{
int magic; // always the bytes 0x49 0x63 0x65 0x50 ("IceP"), i.e. 0x50656349 in little-endian.
byte protocolMajor; // always 1
byte protocolMinor; // always 0
byte encodingMajor; // always 1
byte encodingMinor; // always 0
FrameType frameType;
byte compressionStatus;
int frameSize;
}
```

The `compressionStatus` field is not used or supported by IceRPC. It must be set to 0.

Expand All @@ -39,7 +60,29 @@ The `frameSize` represents the total number of bytes in the frame, including the
A request frame carries an ice request. It consists of a header with the `Request` type followed by a `RequestData`
body:

TODO: ice definitions
```ice
enum OperationMode { Normal = 0, Idempotent = 2 }

struct Identity
{
string name;
string category;
}

sequence<string> Facet;
dictionary<string, string> Context;

struct RequestData
{
int requestId;
Identity id;
Facet facet;
string operation;
OperationMode mode;
Context context;
Encapsulation params;
}
```

A `requestId` with a value greater than 0 uniquely identifies a two-way request on a connection, and must not be reused
while a response for this request is outstanding. The `requestId` 0 is reserved for one-way requests; a one-way request
Expand All @@ -48,7 +91,7 @@ has no corresponding response.
The `id` field corresponds to the path of the outgoing request's service address encoded as an
[Ice identity](/icerpc-for-ice-users/rpc-core/ice-identity).

The `facet` field corresponds to the fragment of the outgoing request's service address encoded as a `Sequence<string>`.
The `facet` field corresponds to the fragment of the outgoing request's service address encoded as a `sequence<string>`.
This sequence is empty when the fragment is empty; otherwise, it has a single element with the fragment.

The `mode` encodes the value of the `Idempotent` [request field][request-fields]. The default is `Normal`.
Expand All @@ -66,46 +109,78 @@ send batch requests and does not accept incoming batch request frames.

A response frame carries an ice response. It consists of a header with the `Reply` type followed by a `ReplyData` body:

TODO: ice definitions
```ice
enum ReplyStatus
{
Ok = 0,
UserException,
ObjectNotExist,
FacetNotExist,
OperationNotExist,
UnknownLocalException,
UnknownUserException,
UnknownException,
InvalidData,
Comment on lines +115 to +123
Copy link
Copy Markdown
Member Author

@bernardnormier bernardnormier Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The commas are required for the Ice syntax (ice code blocks). They are optional for the Slice syntax (slice code block).

Unauthorized
}

struct ReplyData
{
int requestId;
ReplyStatus replyStatus;
byte[...] replyPayload; // pseudo-Ice
}
Comment thread
bernardnormier marked this conversation as resolved.
```

The `requestId` field identifies the request associated with this response.

The `replyStatus` encodes the response's [status code][status-code] as follows:

| Status code | Encoded as reply status |
| --------------------- | -------------------------- |
| Ok | Ok |
| ApplicationError | UserException |
| NotFound | ObjectNotExistException |
| NotImplemented | OperationNotExistException |
| Any other status code | UnknownException |
| Status code | Encoded as reply status |
| --------------------- | ----------------------- |
| Ok | Ok |
Comment thread
bernardnormier marked this conversation as resolved.
| ApplicationError | UserException |
| NotFound | ObjectNotExist |
| NotImplemented | OperationNotExist |
| InvalidData | InvalidData |
| Unauthorized | Unauthorized |
| Any other status code | UnknownException |

When IceRPC receives a response frame, it creates an incoming response with a status code decoded from the reply status:

| Reply status | Decoded as status code |
| -------------------------- | ---------------------- |
| Ok | Ok |
| UserException | ApplicationError |
| ObjectNotExistException | NotFound |
| FacetNotExistException | NotFound |
| OperationNotExistException | NotImplemented |
| Unknown exceptions | InternalError |
| Reply status | Decoded as status code |
| ----------------- | ---------------------- |
| Ok | Ok |
| UserException | ApplicationError |
| ObjectNotExist | NotFound |
| FacetNotExist | NotFound |
| OperationNotExist | NotImplemented |
| InvalidData | InvalidData |
| Unauthorized | Unauthorized |
| All other values | InternalError |

The format of the `replyPayload` depends on the reply status:

| Reply status | Format of the reply payload |
| ------------------- | --------------------------------------------------------------------- |
| Ok | An [encapsulation](#encapsulation) that holds the response's payload. |
| UserException | An [encapsulation](#encapsulation) that holds the response's payload. |
| NotExist exceptions | A `RequestFailedData` encoded with the Ice encoding. |
| Unknown exceptions | The response's error message encoded with the Ice encoding. |
| Reply status | Format of the reply payload |
| ---------------------------- | --------------------------------------------------------------------- |
| Ok | An [encapsulation](#encapsulation) that holds the response's payload. |
| UserException | An [encapsulation](#encapsulation) that holds the response's payload. |
| Any *NotExist* reply status | A `RequestFailedData` encoded with the Ice encoding. |
| Other values | The response's error message encoded with the Ice encoding. |

### RequestFailedData

`RequestFailedData` is a struct that holds the request's path, fragment and operation. The path is encoded as an
`Identity` and the fragment is encoded as a `Sequence<string>`:
`Identity` and the fragment is encoded as a `sequence<string>`:

TODO: ice definitions
```ice
struct RequestFailedData
{
Identity path;
Facet facet;
string operation;
}
```

IceRPC always encodes the path, fragment and operation of the current incoming request in `RequestFailedData` when
sending a response with status code `NotFound` or `NotImplemented` in an ice response frame.
Expand All @@ -124,7 +199,15 @@ from the peer with these status codes.
An encapsulation is a holder for a request or response payload. It holds the payload and encodes the payload size (as
the encapsulation size, equal to the payload size plus 6) and an encoding version:

TODO: ice definitions
```ice
struct Encapsulation
{
int size; // payload size + 6
byte encodingMajor; // always 1
byte encodingMinor; // always 1
byte[...] payload; // pseudo-Ice
}
Comment thread
bernardnormier marked this conversation as resolved.
```

IceRPC does not know (and does not want to know) how a request or response payload is encoded. As far as IceRPC is
concerned, the payload is just a stream of bytes. It's the user of IceRPC that knows how these payloads are encoded; a
Expand All @@ -143,7 +226,7 @@ Ice encoding version 1.1.
For the same reason, when IceRPC receives an encapsulation, it makes sure the encoding version in this encapsulation is
set to 1.1.

[protocol-and-encoding]: https://doc.zeroc.com/ice/3.7/ice-protocol-and-encoding
[Slice]: /slice
[ice-protocol]: https://docs.zeroc.com/ice/3.8/cpp/ice-protocol
[ice-slice]: https://docs.zeroc.com/ice/3.8/csharp/the-slice-language
[status-code]: ../invocation/incoming-response#status-code
[request-fields]: ../invocation/outgoing-request#request-field
2 changes: 1 addition & 1 deletion content/icerpc/invocation/service-address.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,4 +118,4 @@ Relative service addresses underpin [relative proxies] in Slice.
[URI]: https://en.wikipedia.org/wiki/Uniform_Resource_Identifier

[ServiceAddress]: csharp:IceRpc.ServiceAddress
[Ice facet]: https://doc.zeroc.com/ice/latest/client-server-features/facets
[Ice facet]: https://docs.zeroc.com/ice/3.8/cpp/facets
3 changes: 0 additions & 3 deletions content/slice/encoding/user-defined-types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,3 @@ The contact id = 5, name = not set, age = 42 is encoded as:
```

[bit-sequence]: encoding-only-constructs#bit-sequence
[ice-manual-class-encoding]: https://doc.zeroc.com/ice/3.7/ice-protocol-and-encoding/ice-encoding/data-encoding-for-classes
[sliced-format-attribute]: /slice/language-guide/operation#slicedformat-attribute
[variable-length size]: encoding-only-constructs#variable-length-size
Loading