[core] CoMI error codes

[peter van der Stok]

Hi Core,

Michel makes the remark that the production of comi specific error
messages needs a better specification.
I thought that this warranted a discussion on the ML.

Michel's proposal is:
to create a typical CoMI method parsing pseudo code. This pseudo code is
useful to identify which CoAP error codes are generated by the underline
CoAP library and which are generated by the CoMI specific application
logic.

For those errors generated by the CoAP library, we should not require
any payload since such requirement will force implementers to make
changes to the underline CoAP library. In some cases, such changes are
not even possible, no access to source code or not allowed by the
software license.

For CoAP errors generated at the CoMI application logic level, my
recommendation is still to avoid the definition of specific error codes.
Such error code are really useful only if a client can automatically fix
the situation by re-issuing an updated request taking into account the
initial error. However, I don't see such use cases for these errors. One
example of such approach is error code 4.13 (Request Entity Too Large)
which allow a client to switch to block transfer.

If the target for this extra information is debugging, a simple text
message will do the job. This text message can identify for example the
exact leaf and specific error condition (e.g. "ip-address, pattern
mismatch").
______________________________________________

My alternative proposal is:
using the RESTCONF approach, where errors are returned within a YANG
module instance as specified in section 8 of RFC8040 (RESTCONF). The
returned content format would then be /application/yang+cbor as proposed
in an earlier message to this list.


Looking forward to some discussion,

Peter

[Michel Veillette]

Hi Peter and thanks bringing this subject to the mailing list.

To help moving forward with this discussion, I'm proposing the following inputs:

1) The different validations a YANG server is expected to performe are listed in YANG 1.1 section 8.
https://tools.ietf.org/html/rfc7950#section-8.3.1
Each validation correspond to a possible error message.

2) The format of a RESTCONF error message is described in RFC8040 section 7.1.
https://tools.ietf.org/html/rfc8040#section-7.1

3) The pseudo code mentioned by Peter is provided below.
This pseudo code certainly requires improvements, but should be a good starting point.

CoAP method(){
if CoAP resource don't exist
return error 4.04 (Not Found)

if not authorized to access this resource
return error 4.01 (Unauthorized)

if CoAP method code unsupported for the target resource
return error 4.05 (Method Not Allowed)

if CoAP request payload too large
return 4.13 (Request Entity Too Large)

if method GET {
return resource()

if method PUT {
YANG schema validation on payload()
YANG schema validation on updated datastore()
replace resource()
}

if method POST {
if rpc or action resource {
YANG schema validation on payload()
execute rpc or action()
}
else {
YANG schema validation on payload()
YANG schema validation on updated datastore()
create resource()
}

if method DELETE {
YANG schema validation on updated datastore()
remove resource()
}
}

// YANG schema validation are defined in RFC7950 section 8

YANG schema validation on payload() {
if 'Content-Format' is not 'application/cbor'
return error 4.15 (Unsupported Content-Format)

if CBOR deserialization fail
return error 4.00 (Bad Request) with optional error message

if a datanode is unknown
return error 4.00 (Bad Request) with optional error message

if non config leaf
return error 4.00 (Bad Request) with optional error message

if a leaf with invalid type
return error 4.00 (Bad Request) with optional error message

if a leaf with invalid 'range' or 'length' or 'pattern'
return error 4.00 (Bad Request) with optional error message } }
}

YANG schema validation on updated datastore() {
if a 'mandatory' leaf or choice is absent unless one of its ancestors has a 'when' condition or 'if-feature' evaluates to false.
return error 4.00 (Bad Request) with optional error message

if datanodes for more than one 'choice'
return error 4.00 (Bad Request) with optional error message

if datanodes of a 'if-feature' not implemented
return error 4.00 (Bad Request) with optional error message

if 'must' contains fail to evaluate
return error 4.00 (Bad Request) with optional error message

if 'path' referential integrity fail
return error 4.00 (Bad Request) with optional error message

if 'array' or 'array-list' with invalid 'min-elements' of 'max-elements'
return error 4.00 (Bad Request) with optional error message

if one of the 'keys' in a YANG 'list' is missing
return error 4.00 (Bad Request) with optional error message

if the 'unique' constraint of a YANG 'list' fail
return error 4.00 (Bad Request) with optional error message }
}


Regards,
Michel

-----Original Message-----
From: core [mailto:core-***@ietf.org] On Behalf Of peter van der Stok
Sent: Thursday, April 20, 2017 5:34 AM
To: Core <***@ietf.org>
Subject: [core] CoMI error codes

Hi Core,

Michel makes the remark that the production of comi specific error messages needs a better specification.
I thought that this warranted a discussion on the ML.

Michel's proposal is:
to create a typical CoMI method parsing pseudo code. This pseudo code is useful to identify which CoAP error codes are generated by the underline CoAP library and which are generated by the CoMI specific application logic.

For those errors generated by the CoAP library, we should not require any payload since such requirement will force implementers to make changes to the underline CoAP library. In some cases, such changes are not even possible, no access to source code or not allowed by the software license.

For CoAP errors generated at the CoMI application logic level, my recommendation is still to avoid the definition of specific error codes.
Such error code are really useful only if a client can automatically fix the situation by re-issuing an updated request taking into account the initial error. However, I don't see such use cases for these errors. One example of such approach is error code 4.13 (Request Entity Too Large) which allow a client to switch to block transfer.

If the target for this extra information is debugging, a simple text message will do the job. This text message can identify for example the exact leaf and specific error condition (e.g. "ip-address, pattern mismatch").
______________________________________________

My alternative proposal is:
using the RESTCONF approach, where errors are returned within a YANG module instance as specified in section 8 of RFC8040 (RESTCONF). The returned content format would then be /application/yang+cbor as proposed in an earlier message to this list.


Looking forward to some discussion,

Peter