Subject: [core] CoMI error codes

From: peter van der Stok <[email-masked]>
Date: Thu, 20 Apr 2017 11:34:16 +0200

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

---

From: Michel Veillette <[email-masked]>
Date: Thu, 20 Apr 2017 16:46:20 +0000

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:[email-masked]] On Behalf Of peter van der Stok
Sent: Thursday, April 20, 2017 5:34 AM
To: Core <[email-masked]>
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.

Peter

_______________________________________________
core mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/core