From 09dd7214194a8b7ae9869686a14075db3c5f2ff2 Mon Sep 17 00:00:00 2001 From: Wim Van de Meerssche Date: Fri, 20 Jun 2014 11:52:50 +0200 Subject: [PATCH] Some small improvements to operational action section and common sliver info return :error text. --- call-basics.adoc | 13 ++++++------- call-performoperationalaction.adoc | 1 + rspec.adoc | 3 ++- 3 files changed, 9 insertions(+), 8 deletions(-) diff --git a/call-basics.adoc b/call-basics.adoc index 6bc2bf6..e6cbcfe 100644 --- a/call-basics.adoc +++ b/call-basics.adoc @@ -402,15 +402,13 @@ Some AM cannot know if a resource is ready or has stopped, or even in which stat [[SliverOperationalActions]] === Sliver Operational Actions -NOTE: *TODO this section was copied from the AMv3 spec with only minor changes (mostly markup). This sections content might still be moved to better places.* - Operational actions are commands that the aggregate exposes, allowing an experimenter tool to modify or act on a sliver from outside of the sliver (i.e. without logging in to a machine), without modifying the sliver reservation. Actions may cause changes to sliver operational state. The API defines a few operational actions: these need not be supported. AMs are encouraged to support these if possible, but only if they can be supported following the defined semantics. AMs may have their own operational states/state-machine internally. AMs are however required to advertise such states and actions that experimenters may see or use, by using an advertisement RSpec extension (if an AM does not advertise operational states, then tools can not know whether any actions are available). Operational states which the experimenter never sees, need not be advertised. Operational states and actions are generally by resource type. The standard RSpec extension attaches such definitions to the sliver_type element of RSpecs. -The standard advertisement RSpec extension for advertising operational states and actions can be found here, with an example with comments here. +The standard advertisement RSpec extension for advertising operational states and actions can be found link:rspec.html#RSpecExtensions[here]. Tools must use the operational states and actions advertisement to determine what operational actions to offer to experimenters, and what actions to perform for the experimenter. Tools may choose to offer actions which the tool itself does not understand, relying on the experimenter to understand the meaning of the new action. @@ -831,7 +829,7 @@ XML-RPC type:: ":allocation_status": , ":operational_status": , ":expires": , - (optional) ":error": + (optional) ":error": (optional) ":resource_status" : , }, ... @@ -843,8 +841,10 @@ The +:operational_status+ in the sliver info list is required, unless these 2 co * +:operational_status+ is +:pending_allocation+ * +:allocation_status+ is not +:provisioned+. -+:error+ may be omitted entirely but may not be null/None. -+:resource_status+ can be used to describe the resource specific status in more detail than +:operational_status+. ++:error+ is a free form string and may be omitted entirely or be an empty +string+, but it may not be null/None. +The aggregate manager should set this to a string that could be presented to a researcher to give more detailed information about the state of the sliver if an operation failed for a given sliver. + ++:resource_status+ is optional and can be used to describe the resource specific status in more detail than +:operational_status+. <>, <> and <> directly return the basic sliver info list +array+ described above. <>, <>, <> and <> return a +struct+, which contains a sliver info list +array+ and additional info. @@ -932,5 +932,4 @@ Additional rules: NOTE: *TODO this section was copied from the AMv3 spec with only minor changes (mostly markup). This sections content might still be moved to better places.* -A free form string (not null or None), optionally returned per sliver from several method returns (<>, <>, <>, <>, <>, <>). The aggregate manager should set this to a string that could be presented to a researcher to give more detailed information about the state of the sliver if this operation fails for a given sliver. This option is used in particular where an aggregate may successfully perform the operation for some slivers, but not others. See the +:best_effort+ option above. In particular, it is not returned from <>, which is always all-or-nothing. Note that this field may be omitted entirely from the return in most cases, but is required in the return from <>, though it may be empty. The field if present must be a valid string, not null/None. diff --git a/call-performoperationalaction.adoc b/call-performoperationalaction.adoc index c9b8c06..cd4692d 100644 --- a/call-performoperationalaction.adoc +++ b/call-performoperationalaction.adoc @@ -95,5 +95,6 @@ EXPIRED:: The sliver has expired. SEARCHFAILED:: The slice or sliver does not exist at this AM. BUSY:: Slice or sliver is temporarily locked, try again later INPROGRESS:: Requested operation is already in progress +REFUSED:: When requesting an +:update_users+ action while the sliver is in the wrong operational state. diff --git a/rspec.adoc b/rspec.adoc index 8f6c1ae..9fb5656 100644 --- a/rspec.adoc +++ b/rspec.adoc @@ -594,6 +594,7 @@ It is therefore possible to validate just the portion of an RSpec document which It is required that actors that do not support an extension can interact with actors that do support an extension. Thus the information added in an extension must be ignorable. This means: + * When an extension is used in a request, aggregate managers that do not support it, must copy it unmodified into the manifest whenever possible. * When an extensions is used in an advertisement or manifest, clients that do not support it must ignore it. They should not fail because an unknown extension is present. @@ -614,7 +615,7 @@ Because of this, clients should ignore any extension they do not know. TODO Do we need this additional info from http://www.protogeni.net/ProtoGeni/wiki/RSpecExtensions2 : -Anyone can define an extension by specifying a namespace for that extension and hosting a schema document. The schema document they host is independent of the core rspec schema and any other extension schema. +Anyone can define an extension by specifying a namespace for that extension and hosting a schema document. The schema document they host is independent of the core RSpec schema and any other extension schema. We use XML Document Schema Instance directives to specify which namespaces must be validated against which schemas. This allows the use of nearly every XML validator and parser currently available. The only disadvantage is that it is not possible to associate a particular symbol in the extension schema with a particular context in the RSpec schema and enforce validation. This means that it is possible for an incorrect document to allow an extension to pass validation even if it uses an element meant to extend nodes in a link context or vice versa. To make errors of this kind more evident, all extensions should prefix their start symbols with 'foo_' where foo is the context name. ////////////////////////////////