Subject: Re: [IPP] Outline of IPP Resource Object for System Service Spec

From: Michael Sweet <[email-masked]>
Date: Tue, 06 Sep 2016 16:49:34 -0400

Ira,

> On Aug 31, 2016, at 5:50 PM, Ira McDonald <[email-masked]> wrote:
> 
> Hi Mike,
> 
> Apologies for late response.  Been a busy week.
> 
> I like most all of this except for two state names, because they're
> obscure.  The Job state 'pending' has fuzzy applicability here.
> 
> I suggest states/state reasons:
> 
> 'created' - result of Create-Resource

I prefer overloading 'pending' with the 'resource-incomplete' and 'resource-incoming' state-reasons - first, it keeps things consistent/familiar with Jobs and Documents, and second because we've never had a "created but not ready" state anywhere else in the model - that's always been a state-reason, not a first class state.

> 'uploaded' - result of Send-Resource-Data, except when Resource
> stays 'created' w/ state reason 'resource-incoming' (like job-incoming
> in RFC 2911)

I'm not keen on 'uploaded' since the name can be easily misunderstood (the client uploaded the resource, the system/printer did not, it received it...)

Maybe 'available' (one of the previous names we used) instead?  Or just use the 'pending' state with 'resource-available' in the state-reasons (instead of 'none')?

> 'installed' - result of Install-Resource, except when Resource 
> stays 'uploaded' w/ state reason 'resource-installed'

I'm not keen on 'resource-installed' as a state-reason indicating that a request to install the resource has been received.  It sounds more like the resource *has* been installed, which would be incorrect.

> 'canceled' - result of Cancel-Resource, except when Resource
> stays 'created/loaded/installed' w/ state reason 'resource-canceled'

I also think 'aborted' is important to reflect when a resource is canceled by the System, just as we do for Jobs and Documents.

> 'pending-install' meaning "pending but NOT installed" is not symmetric 
> with 'pending-held' meaning "pending AND held"

Perhaps, but for event notifications (and general implementation of resource updates that need a reboot) I think it is important to be able to track a state for resources that need to be installed after a reboot/power cycle.

Also, pending-install could be more akin to processing-stopped than pending-held.

pending -> pending-install -> installed -> canceled   (firmware update - reboot needed)
pending --------------------> installed -> canceled   (application update - no reboot needed)
pending ---------------------------------> canceled   (resource created but canceled by client without installing)
pending ---------------------------------> aborted    (resource created but aborted by system due to errors)

> ...
> PS - Reasoning behind the 'uploaded' state name is potential
> first class Admin operation Send-Resource-URI (for local domain
> authenticated Resource upload by reference rather than value).
> ...

Ugh, please let's not go down that path.  We have basically no real world usage of Print-URI/Send-URI for printing after 16 years.  Even assuming that a managed network would allow a printer to make an outgoing connection at all, allowing a client to point a printer at a URL for a firmware update seems like a recipe for disaster.

> On Wed, Aug 24, 2016 at 6:07 PM, Michael Sweet <[email-masked]> wrote:
> All,
> 
> The following outline summarizes how I see the IPP Resource object working in the System Service specification. Feedback welcome, and we can discuss this at the next regular IPP conference call (Sept 19).
> 
> TL;DR summary: Resource states are 'pending', 'pending-install', 'installed', 'aborted', and 'canceled'. No more "resource-category" attribute. State reasons and status codes for resource format and security errors.
> 
> ........
> 
> IPP Resource Object
> 
> IPP Resource objects contain metadata and associated firmware, software, templates, and other static data files.  Resource objects have a simple life cycle: creation, installation, history, and deletion.  Resource objects can be listed (Get-Resources) or queried (Get-Resource-Attributes) until they are deleted by the System.
> 
> 
>            Table N - IPP Resource Object Operations and Life Cycle
> 
>     Operation                resource-state         resource-state-reasons
>     -----------------------  ---------------------  ----------------------
>     Create-Resource          'pending' (3)          'resource-incomplete'
> 
>     Send-Resource-Data       'pending' (3)          'none'
>                                    OR
>                              'aborted' (8)          'resource-xxx-error'
> 
>     Install-Resource         'pending-install' (4)  'none'
>                                    OR
>                              'installed' (5)        'none'
>                                    OR
>                              'aborted' (8)          'resource-xxx-error'
> 
>     Cancel-Resource          'canceled' (7)         'none'
>                                    OR
>                              'installed' (5)        'none'
> 
>     Get-Resources            All States             All Reasons
>     Get-Resource-Attributes  All States             All Reasons
> 
> 
> Resource Creation Phase
> 
> Resources are created using the Create-Resource operation which creates the object and the Send-Resource-Data operation which provides the data for the resource. The state during creation is 'pending' (3). The state after creation is either 'pending' or 'aborted' (8) if the resource data contains errors or if the Send-Resource-Data operation is not done quickly enough.
> 
> 
> Resource Installation Phase
> 
> Resources are installed using the Install-Resource operation. The state after installation is either 'pending-install' (4) if the Resource data must be installed after a reboot, 'installed' (5) if the Resource data can be installed immediately, or 'aborted' if the Resource data contains errors and cannot be installed.
> 
> 
> Resource History Phase
> 
> Resources in the history phase of their life cycle are in the 'canceled' or 'aborted' states.
> 
> Resources are aborted by the System when it determines the Resource data contains errors, is missing, or has been replaced.
> 
> Resources are canceled using the Cancel-Resource operation. That state after cancellation is 'canceled' (7) unless the Resource cannot be canceled, such as running firmware that must be replaced before it can be canceled.
> 
> Systems delete Resource data when placing a Resource in the 'canceled' or 'aborted' state. Historical resources MUST be retained in these states for at least 300 seconds before deletion of the Resource object by the System service.
> 
> 
> Resource Status Attributes
> 
>     date-time-at-creation (dateTime)
>     date-time-at-history (dateTime)
>     date-time-at-installed (dateTime)
>     resource-data-uri (uri | no-value)
>     resource-format (mimeMediaType)
>     resource-id (integer(1:MAX))
>     resource-job-id (integer(1:MAX))
>     resource-k-octets (integer(0:MAX))
>     resource-printer-id (integer(1:MAX))
>     resource-state (type1 enum)
>     resource-state-message (text(MAX))
>     resource-state-reasons (1setOf type2 keyword)
>     resource-string-version (text(MAX))
>     resource-type (type2 keyword)
>     resource-uuid (uri)
>     time-at-creation (integer(MIN:MAX))
>     time-at-history (integer(MIN:MAX))
>     time-at-installed (integer(MIN:MAX))
> 
> 
> Resource Description Attributes:
> 
>     resource-info (name(MAX))
>     resource-name (name(MAX))
>     resource-owner-col (collection)
>       owner-uri (uri)
>       owner-vcard (1setOf text(MAX))
> 
> 
> "resource-state" values:
> 
>     - 3 ('pending'): state after creation but before installation
>     - 4 ('pending-install'): state after install for resources that require a reboot
>     - 5 ('installed'): state when a resource is installed
>     - 7 ('canceled'): state when a resource has been canceled by Cancel-Resource operation
>     - 8 ('aborted'): state when a resource has been canceled by System service (bad resource, etc.)
> 
> 
> "resource-state-reasons" values:
> 
>     - 'none': No additional state.
>     - 'resource-format-error': The Resource data contains format errors.
>     - 'resource-incomplete': The Resource object has been created but no data has been sent.
>     - 'resource-security-error': The Resource data's digital signature or other security features could not be verified.
>     - 'resource-timeout': The Resource was not installed within the multiple-operation-time-out period.
> 
> "resource-type" values:
> 
>     - 'document': Template for creating Document object.
>     - 'firmware': Executable firmware (reboot generally required).
>     - 'font': Static font.
>     - 'icc-profile': Static ICC profile.
>     - 'image': Static image (icon, logo, etc.)
>     - 'job': Template for creating Job object.
>     - 'software': Executable software/application (reboot generally not required).
>     - 'strings': Static message catalog (strings file).
> 
> "status-code" values (and operations that can return them):
> 
>     - 'successful-ok': All
>     - 'client-error-bad-request': All
>     - 'client-error-forbidden': All
>     - 'client-error-not-authenticated': All
>     - 'client-error-not-authorized': All
>     - 'client-error-not-found': Cancel-Resource
>     - 'client-error-request-entity-too-large': Send-Resource-Data
>     - 'client-error-document-format-not-supported': Send-Resource-Data
>     - 'client-error-attributes-or-values-not-supported': Create-Resource
>     - 'client-error-charset-not-supported': All
>     - 'client-error-conflicting-attributes': Create-Resource
>     - 'client-error-document-security-error': Send-Resource-Data, Install-Resource
>     - 'server-error-internal-error': All
>     - 'server-error-busy': Cancel-Resource, Create-Resource, Send-Resource-Data
>     - (NEW) 'server-error-too-many-resources': Create-Resource
> 
> _________________________________________________________
> Michael Sweet, Senior Printing System Engineer
> 
> _______________________________________________
> ipp mailing list
> [email-masked]
> https://www.pwg.org/mailman/listinfo/ipp
> 

_________________________________________________________
Michael Sweet, Senior Printing System Engineer

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

---

From: Ira McDonald <[email-masked]>
Date: Tue, 6 Sep 2016 19:05:40 -0400

Hi Mike,

I understand your reservations about 'created' (although it's a proper
ISO 10175 state that was perhaps erroneously omitted in IPP/1.1).

I have STRONG reservations about easily misinterpreted compound
state names like 'pending-install'

I've been working on the spec for two days for a release (I hope) later
this week.

I could live with these values of "resource-state":

'pending' - result of Create-Resource

'available' - result of Send-Resource-Data OR keep 'pending' and
set 'resource-incoming' in "resource-state-reasons" (if delayed)

'installed' - result of Install-Resource OR keep 'available' and
set 'install-requested' in "resource-state-reasons" (if delayed)

'canceled' - result of Cancel-Resource OR keep 'installed' and
set 'cancel-requested' in "resource-state-reasons" (if delayed)

'aborted' - result of System decision after any failure of
Send-Resource-Data or Install-Resource (or their delayed
completion

Primary state transitions should NEVER occur until the work
is finished (e.g., delayed install due to wait-for-reboot) - they
should be correctly foreshadowed by state reasons (as above).

I've added Resource History phase and written the 300 seconds
minimum duration stuff (I still can't find the IETF or PWG spec
where we put this for Job History, but I clearly remember this
discussion a long time ago with Pete Zehler).

I'll happily abandon Send-Resource-URI, but I point out that this
means that many Resources cannot be installed by a limited
capacity mobile phone (e.g., licensed fonts are typically on a
managed server before installation on a printer or app server).

There is a problem with having the Job specify "resource-ids"
for previously installed Resources, to whit, the scope of the
Resource (new value of "resource-job-id") changes AFTER the
Resource is created.  How then would the System know to
automatically cancel the Resource after the Job completes?
Instead, I imagined submitting the the Job into 'pending-held',
creating/uploading/installing any single-Job-scope Resources
with proper values of "resource-job-id".  Please puzzle this one
out a bit more.  I suppose/presume there's a similar ambiguity
for a Printer-scope Resource?

BTW - Although I reorganized section 6 into subsections for
Printer, Resource, System, and Subscription operations, this
made a thorough mess of all the cross-references to section 6
(not to be fixed up in this next draft, probably - I'm trying to get
at least something in for all the model comments from the F2F).

Cheers,
- Ira

Ira McDonald (Musician / Software Architect)
Co-Chair - TCG Trusted Mobility Solutions WG
Chair - Linux Foundation Open Printing WG
Secretary - IEEE-ISTO Printer Working Group
Co-Chair - IEEE-ISTO PWG Internet Printing Protocol WG
IETF Designated Expert - IPP & Printer MIB
Blue Roof Music / High North Inc
http://sites.google.com/site/blueroofmusic
http://sites.google.com/site/highnorthinc
mailto: [email-masked]
Jan-April: 579 Park Place  Saline, MI  48176  734-944-0094
May-Dec: PO Box 221  Grand Marais, MI 49839  906-494-2434

On Tue, Sep 6, 2016 at 4:49 PM, Michael Sweet <[email-masked]> wrote:

> I prefer overloading 'pending' with the 'resource-incomplete' and
> 'resource-incoming' state-reasons - first, it keeps things
> consistent/familiar with Jobs and Documents, and second because we've never
> had a "created but not ready" state anywhere else in the model - that's
> always been a state-reason, not a first class state.
>
> I'm not keen on 'uploaded' since the name can be easily misunderstood (the
> client uploaded the resource, the system/printer did not, it received it...)
>
> Maybe 'available' (one of the previous names we used) instead?  Or just
> use the 'pending' state with 'resource-available' in the state-reasons
> (instead of 'none')?
>
> I'm not keen on 'resource-installed' as a state-reason indicating that a
> request to install the resource has been received.  It sounds more like the
> resource *has* been installed, which would be incorrect.
>
> I also think 'aborted' is important to reflect when a resource is canceled
> by the System, just as we do for Jobs and Documents.
>
> Perhaps, but for event notifications (and general implementation of
> resource updates that need a reboot) I think it is important to be able to
> track a state for resources that need to be installed after a reboot/power
> cycle.
>
> pending ---------------------------------> canceled   (resource created
> but canceled by client without installing)
> Ugh, please let's not go down that path.  We have basically no real world
> usage of Print-URI/Send-URI for printing after 16 years.  Even assuming
> that a managed network would allow a printer to make an outgoing connection
> at all, allowing a client to point a printer at a URL for a firmware update
> seems like a recipe for disaster.
>
>
>
> > The following outline summarizes how I see the IPP Resource object
> working in the System Service specification. Feedback welcome, and we can
> discuss this at the next regular IPP conference call (Sept 19).
> >
> > TL;DR summary: Resource states are 'pending', 'pending-install',
> 'installed', 'aborted', and 'canceled'. No more "resource-category"
> attribute. State reasons and status codes for resource format and security
> errors.
> >
> > ........
> >
> > IPP Resource Object
> >
> > IPP Resource objects contain metadata and associated firmware, software,
> templates, and other static data files.  Resource objects have a simple
> life cycle: creation, installation, history, and deletion.  Resource
> objects can be listed (Get-Resources) or queried (Get-Resource-Attributes)
> until they are deleted by the System.
> >
> >
> > Resources are created using the Create-Resource operation which creates
> the object and the Send-Resource-Data operation which provides the data for
> the resource. The state during creation is 'pending' (3). The state after
> creation is either 'pending' or 'aborted' (8) if the resource data contains
> errors or if the Send-Resource-Data operation is not done quickly enough.
> >
> >
> > Resources are installed using the Install-Resource operation. The state
> after installation is either 'pending-install' (4) if the Resource data
> must be installed after a reboot, 'installed' (5) if the Resource data can
> be installed immediately, or 'aborted' if the Resource data contains errors
> and cannot be installed.
> >
> >
> > Resource History Phase
> >
> > Resources are aborted by the System when it determines the Resource data
> contains errors, is missing, or has been replaced.
> >
> > Resources are canceled using the Cancel-Resource operation. That state
> after cancellation is 'canceled' (7) unless the Resource cannot be
> canceled, such as running firmware that must be replaced before it can be
> canceled.
> >
> > Systems delete Resource data when placing a Resource in the 'canceled'
> or 'aborted' state. Historical resources MUST be retained in these states
> for at least 300 seconds before deletion of the Resource object by the
> System service.
> >
> >
> >     - 'resource-security-error': The Resource data's digital signature
> or other security features could not be verified.

---

From: Ira McDonald <[email-masked]>
Date: Tue, 6 Sep 2016 20:25:14 -0400

Hi Mike,

Further thoughts about "resource-printer-id" and "resource-job-id".

Delete them.  Several Printers and/or Jobs could need a Resource
(and would have a pointer to indicate that), but the Resource should
NOT have pointers.  That is, all Resources are (as we agreed) of
System scope and can only be managed (or state affected) by the
System Service.

WDYT?

Cheers,
- Ira

On Tue, Sep 6, 2016 at 7:05 PM, Ira McDonald <[email-masked]>
wrote:

>> I'm not keen on 'uploaded' since the name can be easily misunderstood
>> (the client uploaded the resource, the system/printer did not, it received
>> it...)
>>
>> I also think 'aborted' is important to reflect when a resource is
>> canceled by the System, just as we do for Jobs and Documents.
>>
>> > IPP Resource objects contain metadata and associated firmware,
>> software, templates, and other static data files.  Resource objects have a
>> simple life cycle: creation, installation, history, and deletion.  Resource
>> > Resources are aborted by the System when it determines the Resource
>> data contains errors, is missing, or has been replaced.
>> >

---

From: Michael Sweet <[email-masked]>
Date: Fri, 09 Sep 2016 12:00:04 -0400

Ira,

> On Sep 6, 2016, at 7:05 PM, Ira McDonald <[email-masked]> wrote:
> 
> Hi Mike,
> 

I'm looking at 10175 right now...  The table of attributes for the Document object in section 9.8 lists the generic "state" and a more specific "document-state".

"state" is defined in section 9.1.6.4 and lists the following values: "ready", "initializing", "on-request", "unavailable", "busy", "terminating", and "unknown".

"document-state" is defined in section 9.3.5.2 and lists the following values: "transfer-pending", "pending", "processing", "printing", and "completed".

I don't see 'created' as a state.

> should be correctly foreshadowed by state reasons (as above).

I'm fine with this.

> managed server before installation on a printer or app server).

I'll point out that mobile phones are not typically primary management devices.  But if somebody did choose to use a mobile phone for this, said phone will likely have multiple gigabytes of storage available and regardless will be perfectly capable of streaming content from a trusted server to the local printer via Send-Resource-Data, using authentication and policy information available only on said phone.  And said phone is far more likely to have current security updates installed than said printer.

> automatically cancel the Resource after the Job completes?

I think since we decided not to allow Resources to be created by ordinary users for a Job, we no longer have Job-scoped resources.  Resources specified in a Job Creation request (via the "resource-ids" operation attribute) naturally must be retained for the life of the Job, but that can be implemented fairly simply (reference counts, etc.)

> for a Printer-scope Resource?

I don't think we do, since Printer Resource creation is an administrative operation and not a user operation.

---

From: Michael Sweet <[email-masked]>
Date: Fri, 09 Sep 2016 12:00:59 -0400

Ira,

> On Sep 6, 2016, at 8:25 PM, Ira McDonald <[email-masked]> wrote:
> 
> Hi Mike,
> 

That makes sense for Jobs.  I'm not sure for Printers, where ICC profiles, icons, etc. might very well be Printer-specific.

---

From: Ira McDonald <[email-masked]>
Date: Fri, 9 Sep 2016 13:54:21 -0400

Hi Mike,

Thanks for both replies.  I got stalled on editing for a few days, but
I did get a lot of this latest thinking in on Monday and Tuesday and
will return to editing this weekend.

I agree with all of your comments.

Pedantic DPA background stuff:

ISO-10175 Part 3 defines the Create operation on pages 10 to 15,
which normally results (for a Printer object) in a Printer with initial
state of 'unknown' (not an out-of-band value).

ISO-10175 Part 1 defines "printer-state" on pages 185 to 186 with
a long list of values (most of which were moved CORRECTLY to
"printer-state-reasons" in IPP) including the indeterminate state
of 'unknown'.

ISO-10175 Part 1 defines "current-job-state" on pages 125 to 126,
also including 'unknown'.

In DPA implementations at a printer vendor where I once consulted,
'unknown' was used as the initial state result of a Create operation
for either a Printer or a Job, because they wanted Create to return
quickly.

Cheers,
- Ira

On Fri, Sep 9, 2016 at 12:00 PM, Michael Sweet <[email-masked]> wrote:

> That makes sense for Jobs.  I'm not sure for Printers, where ICC profiles,
> icons, etc. might very well be Printer-specific.
>