Jump to: navigation, search

Difference between revisions of "Zaqar/specs/endpoint"

m (→‎QueuesController)
m (Malini moved page Marconi/specs/endpoint to Zaqar/specs/endpoint: Project Rename)
 
(19 intermediate revisions by 2 users not shown)
Line 11: Line 11:
  
 
Storage drivers export 3 controllers which group endpoints by resource.
 
Storage drivers export 3 controllers which group endpoints by resource.
 +
 +
TODO(kgriffs): Define params and valid ranges for each.
  
 
=== QueueController ===
 
=== QueueController ===
  
−
* Create Queue (create_queue)
+
* List Queues
−
* Set queue metadata (set_queue_meta)
+
** Return list of queue names in alphabetical order
−
* Get queue metadata (get_queue_meta)
+
** Optional marker, limit params to support paging
−
* Delete Queue (delete_queue)
+
** Optionally include queue metadata in listing
−
* Get queue status (get_queue_status)
+
* Get queue metadata
 +
* Upsert Queue
 +
** Queue names may not exceed 512 bytes in length
 +
** Can specify arbitrary metadata (optional).
 +
** Top-level field names in the metadata document MUST NOT start with the underscore character as it is reserved for future use.
 +
** Metadata is limited to 4 KiB in size
 +
** (For Updates) The document that the client provides will completely overwrite existing metadata (partial updates are planned for a future release)  
 +
* Delete Queue
 +
* Get queue stats
 +
** Messages: total, claimed, and expired (but not yet scrubbed)
 +
* Get Actions
 +
** Delete message
 +
** Claim messages
 +
** Update claim
 +
** Release claim
 +
** Claim expired
 +
** Message expired
 +
 
 +
 
 +
==== Note about action messages ====
 +
 
 +
TODO: This has been postponed to a post-v1.0 release.
 +
 
 +
The interactions of various agents/workers with a cloud queuing services can be difficult to audit and debug. Marconi emits action messages to a special queue (hence action messages use the same format as regular messages), from which auditors can retrieve a list of recent actions involving a specific queue's messages. These actions can then be archived by the auditor for future analysis and diagnostics.
 +
 
 +
Action messages expire after 5 minutes, so auditors should regularly poll for actions and persist them for posterity.
  
−
=== MessagesController ===
+
=== MessageController ===
  
−
* Get Message (get_message)
+
* Get Message(s)
−
* Get Messages (get_messages)
+
* Post Message(s)
−
* Get Action Messages (get_actions)
+
* Delete Message
−
* Post Message(s) (post_messages)
 
−
* Delete Message (delete_message)
 
  
−
=== ClaimsController ===
+
=== ClaimController ===
  
−
* Claim Message (claim_message)
+
* Claim messages
−
* Query claim (query_claim)
+
** Storage driver makes a best-effort attempt to return the requested number of messages, but may return fewer.
−
* Update claim (update_claim)
+
* Query claim
−
* Release Claim (release_claim)
+
* Update claim
 +
* Release Claim
 +
* Claim Stats
  
 
== Transport-Specific ==
 
== Transport-Specific ==

Latest revision as of 18:42, 7 August 2014

Marconi Endpoints

Endpoints define the protocol between a given transport and the storage driver. In this way, multiple transports like HTTP and ZMQ can be supported; they are not exclusive and can be enabled directly from the config file.

Related endpoints are grouped into one of several controllers, who's interface is defined by an abstract base class. The storage driver provides a concrete implementation for each controller type.

For specific implementations read: HTTP, ZMQ

Common Endpoints, exposed by Storage Drivers

Storage drivers export 3 controllers which group endpoints by resource.

TODO(kgriffs): Define params and valid ranges for each.

QueueController

  • List Queues
    • Return list of queue names in alphabetical order
    • Optional marker, limit params to support paging
    • Optionally include queue metadata in listing
  • Get queue metadata
  • Upsert Queue
    • Queue names may not exceed 512 bytes in length
    • Can specify arbitrary metadata (optional).
    • Top-level field names in the metadata document MUST NOT start with the underscore character as it is reserved for future use.
    • Metadata is limited to 4 KiB in size
    • (For Updates) The document that the client provides will completely overwrite existing metadata (partial updates are planned for a future release)
  • Delete Queue
  • Get queue stats
    • Messages: total, claimed, and expired (but not yet scrubbed)
  • Get Actions
    • Delete message
    • Claim messages
    • Update claim
    • Release claim
    • Claim expired
    • Message expired


Note about action messages

TODO: This has been postponed to a post-v1.0 release.

The interactions of various agents/workers with a cloud queuing services can be difficult to audit and debug. Marconi emits action messages to a special queue (hence action messages use the same format as regular messages), from which auditors can retrieve a list of recent actions involving a specific queue's messages. These actions can then be archived by the auditor for future analysis and diagnostics.

Action messages expire after 5 minutes, so auditors should regularly poll for actions and persist them for posterity.

MessageController

  • Get Message(s)
  • Post Message(s)
  • Delete Message

ClaimController

  • Claim messages
    • Storage driver makes a best-effort attempt to return the requested number of messages, but may return fewer.
  • Query claim
  • Update claim
  • Release Claim
  • Claim Stats

Transport-Specific

The following endpoints only apply to specific transports.

WSGI

  • Node health (test_reachable)
  • Get home document
Retrieved from "https://wiki.openstack.org/w/index.php?title=Zaqar/specs/endpoint&oldid=60024"