Subject: IPP> MOD - Proposal for status code keywords in the Model document

From: [email-masked]
Date: Fri, 9 May 1997 13:14:27 -0500

This note contains:
    1) Proposed status code keyword definitions for the Model document
    2) Mapping of Bob Herriot's analysis of HTTP 1.1 to Model status
       codes
    3) Issues (and in some cases proposed answers)
  Note that I added a prefix "OK" or "error" to each status keyword so an
  IPP application can detect the class of status code upfront.

  Enjoy,

  Keith
    1.0 PROPOSED STATUS CODE DEFINITIONS FOR THE MODEL DOCUMENT
    -----------------------------------------------------------
    4.3 Status and Message
    The Status code provides information on the results of a request.
    The Message provides a short textual description of the Status.
    The Status is intended for use by automata and the Message is
    intended for the human user.  An IPP application (i.e. a browser,
    GUI, print driver or gateway) is not required to examine or
    display the Message.
    4.4 Status Codes (type2 keyword)
    Each Status is described below, including a description of which
    operation(s) it can follow and any metainformation required in
    the response.
    4.4.1 Successful Status Codes
    This class of status code indicates that the client's request was
    successfully received, understood, and accepted.
    4.4.1.1 OK
    The request has succeeded. The information returned with the
    response is dependent on the operation, for example:
       CreateJob             A Job is created and the Job URL is returned
                             in the response;
       SendDocument          Data is written to a Document in a Job;
       Cancel                The Job is cancelled;
       Get-Jobs              The Jobs currently belonging to the
                             Printer are returned in the response;
       Get-Attributes        The values for the attributes specified
                             in the request are returned in the
                             response.
    4.4.1.2 OK-attribute-not-implemented (NEW)
    The operation has succeeded.

    On a Get-Attributes operation, if an IPP Printer encounters any
    attributes in the request that are not implemented, the Printer
    shall return this status and indicate in the response which
    attributes are not supported by the Printer.
    On a Get-Jobs operation, if an IPP Printer encounters any
    attributes in the request that are not implemented and the values
    (if specified) for Job Owner and Job States are supported by the
    Printer, the Printer shall return this status and indicate in the
    response which attributes are not supported by the Printer.
    4.4.1.3 OK-attribute-ignored-or-value-substituted
    The operation has succeeded.  On a CreateJob operation, the request
    specifies substitute-as-needed for the best-effort attribute.  In
    response to the CreateJob, the IPP Printer substituted a
    value for at least one attribute value that is not supported
    and/or ignored at least one attribute that is not implemented.
    In practice, an IPP application should avoid this situation by
    querying an IPP object for its valid attributes and values
    before performing an operation on the object.
    4.4.2 Error Status Codes
    This class of status code is intended for cases in which there is
    an error.  IPP applications should display any included Message
    to the end-user.  Unless otherwise noted, these status codes apply
    to all operations.
    4.4.2.1 error-bad-request
    The request could not be understood by the IPP Printer due to
    malformed syntax.  The IPP application should not repeat the
    request without modifications.
    4.4.2.2 error-user-authentication-required
    The request requires user authentication.
    4.4.2.3 error-payment-required
    This request requires payment by the end-user to perform the
    CreateJob operation.
    4.4.2.4 error-forbidden-operation
    The IPP Printer understood the request, but is refusing to fulfill
    it.  Authorization will not help and the request should not be
    repeated.  This status code is commonly used when the IPP Printer
    does not wish to reveal exactly why the request has been refused
    or when no other response is applicable.
    4.4.2.5 error-operation-not-allowed

    The operation is not allowed for the object identified by the
    URL.  For example, a CreateJob operation is not allowed on a Job
    object specified by a Job URL.
    4.4.2.6 error-operation-not-authorized
    The request requires that an end-user have access to an object
    and the authorization to perform an operation on the object.  For
    example, an end-user might be authorized to list others' Jobs but
    the end-user is not authorized to cancel others' Jobs.  For
    another example, an end-user might not have access to a Printer
    either because the end-user is not defined in the access control
    list for the Printer or the end-user does not have access to the
    Printer across a firewall.
    4.4.2.7 error-URL-not-found
    The server name in the URL is not found or the server cannot find
    the object specified in the URL. No indication is given of
    whether the condition is temporary or permanent.
    An application should use a Directory Service to return a list of
    valid Printer URLs and use the GetJobs operation to return a list
    of valid Job URLs for a Printer so an end-user can select from a
    valid list of URLs.
    4.4.2.8 error-URL-gone
    The requested object is no longer available to the server specified
    in the URL.  This condition should be considered permanent. Clients
    with link editing capabilities should delete references to the URL
    after user approval.  This response is cachable.
    This response is primarily intended to notify the recipient that
    the resource is intentionally unavailable and that the server
    owners desire that remote links to that resource be removed. Such
    an event is common for resources belonging to individuals no
    longer working at a site.
    4.4.2.9 error-URL-too-long

    The server specified in the URL is refusing to service the request
    because the URL is longer than the server is willing to interpret.
    This condition is only likely to occur when an IPP application allows
    an end-user to type an invalid URL for an IPP object and then
    specifies that URL on an operation.  An application should use a
    Directory Service to return a list of valid Printer URLs and use
    the Get-Jobs operation to return a list of valid Job URLs for a
    Printer so an end-user can select from a valid list of URLs.
    4.4.2.10 error-attribute-not-implemented-or-value-not-supported
    For a CreateJob operation, if the IPP Printer does not implement at
    least one attribute and/or at least one attribute value in the
    request and either the request specifies do-not-substitute for
    the best-effort attribute or the Printer cannot process the
    request correctly, the Printer shall return this status.

    For example, if the Print operation specifies do-not-substitute
    for the best-effort attribute, the request requires A4 paper and
    that paper size is not supported by the Printer, the Printer shall
    return this status.
    For a Get-Jobs operation, if the IPP Printer does not support at
    least one attribute value for Job Owner and/or Job States in
    the request, the Printer shall return this status.
    In practice, an IPP application should avoid this situation by
    querying an IPP Printer for its valid attributes and values
    before performing a Print operation on the Printer.
    4.4.2.11 error-internal-server-error
    The IPP Printer encountered an unexpected condition which
    prevented it from fulfilling the request.
    4.4.2.12 error-service-unavailable
    The IPP Printer is currently unable to handle the request due to a
    temporary overloading or maintenance of the Printer.  The
    implication is that this is a temporary condition which will be
    alleviated after some delay. If known, the length of the delay
    may be indicated in the Message.  If no delay is given, the IPP
    application should handle the response as it would for a 200
    response.
    4.4.2.13 error-IPP-version-not-supported
    The IPP Printer does not support, or refuses to support, the IPP
    protocol version that was used in the request message. The IPP
    Printer is indicating that it is unable or unwilling to complete
    the request using the same major version as the client other than
    with this error message. The response should contain a Message
    describing why that version is not supported and what other
    versions are supported by that IPP Printer.
    A conforming IPP client shall specify the valid version for IPP 1.0
    on each request.  A conforming IPP server shall not return this
    status code to a conforming IPP 1.0 client.  An IPP server shall
    return this status code to a non-conforming IPP client.
    4.4.2.14 error-operation-not-implemented
    The IPP Printer does not support the functionality required to
    fulfill the request. This is the appropriate response when the
    IPP Printer does not recognize an operation and is not capable of
    supporting it for any object.
    4.4.2.15 error-printer-error
    A printer error, such as a paper jam, occurs while the IPP Printer
    processes a SendDocument operation.  The response shall contain the
    Job Status with the specific error and should contain a Message
    describing the error.  An IPP application should check the Job Status
    in the response for the specific error.
    4.4.2.16 error-write-fault (NEW)
    A write error, such as a memory overflow (i.e. the document data
    exceeds the memory of the Printer) or a disk full condition, occurs
    while the IPP Printer processes a SendDocument operation.  The
    IPP application must check the Bytes Written in the response to
    determine how many bytes were actually successfully processed by the
    Printer.
    4.4.2.17 error-document-rejected (NEW)
    The Printer cannot process a Document in a Job for one of the
    following reasons: (1) the document-format of a document is not
    supported by the Printer (2) the document exceeds number-of-documents
    supported by the Printer.  For example, if a Job contains multiple
    documents and the Printer supports the document-format(s) of some,
    but not all, of these documents, then the Printer returns this Status
    when it first encounters an unsupported document-format.
    4.4.2.18 error-unknown (NEW)
    The IPP client encountered an unexpected condition which prevented
    it from fulfilling the request.  The response should contain a
    Message describing the error.

    2.0 UPDATE TO BOB'S ANALYSIS OF HTTP 1.1 AND MODEL STATUS CODES
    ---------------------------------------------------------------
    This section is a copy of Bob's note with his analysis of my original
    proposal except that I have replaced the IPP status code values with
    IPP status code keywords.  I have tried to capture differences in the
    Issues section of this note.
    Marks in column 1 denote:
      x should be in IPP Version 1.0
      f may be in a future version, do don't reuse error code
      i new concept in IPP not in HTTP (these error codes start at x51)
      <blank> HTTP codes that IPP probably doesn't need but don't
         suggest reusing them
    A k in column 2 indicates the status code is in Keith's proposal as
    defined in this note.
    The proposed IPP status code keyword is to the right of its
    corresponding HTTP 1.1 status code where appropriate.
       Informational 1xx
    f    100 Continue
    f    101 Switching Protocols
       Successful 2xx
    xk   200 OK -> OK
    x    201 Created (for CreateJob instead of 200) -> OK (see Issue #1)
    f    202 Accepted
         203 Non-Authoritative Information
    x    204 No Content (e.g. CancelJob) -> OK (see Issue #1)
         205 Reset Content
         206 Partial Content
    ik   251 Attribute Substitution/Ignored ->
             OK-attribute-ignored-or-value-substituted
       Redirection 3xx
         300 Multiple Choices
    f    301 Moved Permanently
    f    302 Moved Temporarily
         303 See Other
    f    304 Not Modified
         305 Use Proxy
       Client Error 4xx
    xk   400 Bad Request -> error-bad-request
    xk   401 Unauthorized -> error-user-authentication-required
    xk   402 Payment Required -> error-payment-required
    xk   403 Forbidden -> error-forbidden-operation
    xk   404 Not Found -> error-URL-not-found
    xk   405 Method Not Allowed -> error-operation-not-allowed
    x    406 Not Acceptable (see Issue #2)
         407 Proxy Authentication Required
    f    408 Request Timeout
         409 Conflict
    xk   410 Gone -> error-URL-gone
    x    411 Length Required (see Issue #3)
         412 Precondition Failed
    x    413 Request Entity Too Large (see Issue #3)
    xk   414 Request-URI Too Long -> error-URL-too-long
         415 Unsupported Media Type
    ik   451 Attribute Not Implement/Value Not Supported ->
             error-attribute-not-implemented-or-value-not-supported
     k   45x not defined -> error-operation-not-authorized (see Issue #4)
       Server Error 5xx
    xk   500 Internal Server Error -> error-internal-server-error
    xk   501 Not Implemented -> error-operation-not-implemented
         502 Bad Gateway
    xk   503 Service Unavailable -> error-service-unavailable
         504 Gateway Timeout
    xk   505 HTTP Version Not Supported ->
             error-ipp-version-not-supported
     k   551 Printer Error -> error-printer-error
    3.0 ISSUES
    ----------
    Based on previous email on my original proposal, I documented the
    following issues.  Any mistakes in articulating the issue are mine.
    1.  Should there be a single OK status returned for all operations
        that are performed successfully (i.e. asserting there is no
        attribute or value substitution) or should there be more granular
        status codes in the following cases?
        Operation     IPP     HTTP 1.1
        ---------     ---     --------
        CreateJob     OK  vs. Created (201) (i.e. a Job is created)
        SendDocument  OK  vs. Created? (201) (i.e. a Document is created)
        CancelJob     OK  vs. No Content (204) (i.e. no entity body
                                                returned)
        PROPOSAL:  Use a single OK status keyword in IPP for all
        operations.  Other implementations might not have the same
        underlying status codes as HTTP 1.1.  An HTTP 1.1 implementation
        can map Created and No Content to OK.
    2.  HTTP 1.1 defines a status code of Not Acceptable (406). The HTTP
        RFC states:  "The resource identified by the request is only
        capable of generating response entities which have content
        characteristics not acceptable according to the accept headers
        sent in the request."
        Should there be an IPP status code for this error?
    3.  HTTP 1.1 defines status codes Length Required (411) and Request
        Entity Too Large (413).
        Length Required means the "The server refuses to accept the
        request without a defined Content-Length".  This seems like a
        bug in the implementation of an IPP client.
        Request Entity Too Large means "The server is refusing to process
        a request because the Request-URI is longer than the server is
        willing to interpret."
        Should there be IPP status codes for these errors?
    4.  This proposal defines Status codes user-authentication-required,
        operation-not-authorized and operation-forbidden.
        HTTP 1.1 defines Unauthorized (401) which maps to
        user-authentication-required and Forbidden (403) which maps to
        operation-forbidden.  I added operation-not-authorized because I
        believe this is a separate error per the definition of
        authentication and authorization in the IPP Security internet
        draft.
        Should all 3 status codes be in the IPP Model, a subset or a
        superset?
        PROPOSAL: Keith will request a position from the Security group.
    5.  Should there be a status code for attribute-substition and
        another status for attribute-ignored instead of a single status
        code?
        ANSWER: Use 1 status code,
        OK-attribute-ignored-or-value-substituted
        since both conditions can occur for the same operation.
    6.  Should there be a status code for attribute-not-implemented and
        another status for attribute-value-not-supported instead of a
        single status code?
        ANSWER: Use 1 status code,
        error-attribute-not-implemented-or-value-not-supported,
        since both conditions can occur for the same operation.
    7.  Should there be a status code ipp-version-not-supported?
        PROPOSAL:  Yes.  Keith will write up a section for the Model
        document on IPP version.
    8.  Should there be a way for implementors to have private error
        codes?
        PROPOSAL:  Since Status codes are type2 keywords, "implementors
        can,at any time, add new values by proposing them to the PWG for
        registration (or an IANA-appointed registry advisor after the PWG
        is no longer certified) where these are reviewed for approval".
        Is this sufficient?
    9.  Since multiple documents isn't indicated by an attribute, but
        rather by the content that is sent, we need a distinct error
        code:multiple-documents-not-supported (if we allow a conforming
        Printer to reject a multiple document job in a Print operation).
        The description of number-of-documents states the following: "The
        printer shall reject a job if the number of documents is not in
        the range of this attribute".
        PROPOSAL:  The error is really that a Printer receives a Job with
        n+1 documents where the Printer can only support n documents per
        Job.  So the error isn't limited to whether one or more than one
        Document is supported per job.  I added document-rejected
        (see above) to cover this and another case.