Skip to content

Latest commit

 

History

History
53 lines (35 loc) · 3.38 KB

error_model.adoc

File metadata and controls

53 lines (35 loc) · 3.38 KB
Raw

uProtocol Error Model (UStatus)

Table of Contents

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in IETF BCP14 (RFC2119 & RFC8174)

SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation

See the NOTICE file(s) distributed with this work for additional
information regarding copyright ownership.

This program and the accompanying materials are made available under
the terms of the Apache License Version 2.0 which is available at
https://www.apache.org/licenses/LICENSE-2.0

SPDX-FileType: DOCUMENTATION
SPDX-License-Identifier: Apache-2.0

uProtocol supports invoking operations on (remote) service providers by means of Remote Procedure Calls (RPC). In order to do so, a client uEntity (service consumer) sends an RPC Request message to the service provider and waits for a corresponding RPC Response message which conveys the outcome of the invocation of the operation.

In general, an RPC can succeed or fail from the service consumer’s point of view. In the former case, the response message contains the data/information that is the result of successfully processing the input data conveyed in the request message. In the latter case, the response message contains details regarding the reason why processing of the request message has failed.

uProtocol follows Google’s protocol-agnostic API error model. In particular, a service consumer MUST consider an RPC as failed if the commstatus property contained in the response message attributes has a value other than OK. In that case the response message’s payload MUST be a serialized UStatus containing detail information about the reason for failure.

1. Service Interface Design

uProtocol uses Protobuf for defining a service provider’s operations. Based on the error model defined above, the Protobuf Message defined/used as the response of an operation SHOULD only contain the data/information that represents the outcome of successful execution of the operation.

If an operation does not return any data/information on successful execution, the operation SHOULD use a dedicated empty response Message:

service HvacService {
  rpc SetTemperature(SetTemperatureRequest) returns (SetTemperatureResponse);
}

message SetTemperatureRequest {
    uint32 temperature = 1;
}

message SetTemperatureResponse {}

A service consumer invoking this operation will then receive a UMessage with an empty payload.

2. Service Implementation

In case of successful execution of a service operation, a service provider MUST put the operation’s response Protobuf Message into the response UMessage's payload and MUST set its commstatus attribute to value OK.

In case of erroneous execution, a service provider SHOULD put a UStatus Message into the response UMessage's payload and set its commstatus attribute to the same value as the UStatus' code property.