CL-SQS
An interface to the Amazon Web Services Simple Queue Service
Abstract
CL-SQS is a Common Lisp library for interfacing with the Amazon Simple Queue Service (see Amazon Web Services for details). It uses the Query API to access Amazon SQS.The code comes with a BSD-style
license so you can basically do with it whatever you
want.
Contents
- Usage example
- Download
- Installation and dependencies
- Known bugs and limitations
- The CL-SQS dictionary
- Acknowledgments
Usage example
CL-USER> (setf sqs:*amazon-aws-access-key-id* "my_example_aws_id")
"my_example_aws_id"
CL-USER> (setf sqs:*amazon-aws-secret-access-key* "my_very_secret_aws_key")
"my_very_secret_aws_key"
CL-USER> (sqs:list-queues)
NIL
((:REQUEST-ID . "0f4e999a-2cbe-4a10-a1ed-507d95bdff02")
(:STATUS . "Success"))
CL-USER> (defparameter *q1* (sqs:create-queue "jwr1"))
*Q1*
CL-USER> (defparameter *q2* (sqs:create-queue "jwr2"))
*Q2*
CL-USER> *q1*
"http://queue.amazonaws.com/A2BTL5N0PIKMOT/jwr1"
CL-USER> (sqs:send-message *q1* "Test message #1")
T
((:REQUEST-ID . "51c6068f-d0d9-4de7-ab4d-eb1409422092")
(:STATUS . "Success"))
CL-USER> (sqs:receive-message *q1*)
(("0M9JVG2K9X3P83FD05Q7|C9345G3K2XDCVZ7R7FH1|RW2145BC0M6GHC5ZPAC1"
. "Test message #1"))
((:REQUEST-ID . "f61331ad-bc5c-4525-8f59-e06e9d95930f")
(:STATUS . "Success"))
CL-USER> (sqs:list-queues "jwr")
("http://queue.amazonaws.com/A2BTL5N0PIKMOT/jwr1"
"http://queue.amazonaws.com/A2BTL5N0PIKMOT/jwr2")
((:REQUEST-ID . "4b341942-77e8-4d35-98ff-82dcb02310b7")
(:STATUS . "Success"))
CL-USER> (mapcar #'sqs:delete-queue (sqs:list-queues))
(T T)
CL-USER>
Download
CL-SQS releases are listed on the download page.Installation and dependencies
CL-SQS depends on the following libraries being installed:- DRAKMA - A Common Lisp web client (you will need to run at least 0.10.1)
- ironclad (for HMAC-SHA1)
- iterate
- s-xml
Known bugs and limitations
The following API functions are missing:- AddGrant
- ListGrants
- RemoveGrant
The CL-SQS dictionary
[Special variable]
*amazon-aws-access-key-id*
Amazon Web Services public access key ID
[Special variable]
*amazon-aws-secret-access-key*
Amazon Web Services secret access key
[Function]
change-message-visibility
queue-url message-id visibility-timeout =>
result
Change the visibility of the message specified by QUEUE-URL and MESSAGE-ID to VISIBILITY-TIMEOUT.
[Function]
create-queue name
&key default-visibility-timeout =>
result
Creates a queue with a given NAME. Returns the queue URL if successful. DEFAULT-VISIBILITY-TIMEOUT can be set at creation time for the entire queue.
[Function]
delete-message queue-url
message-id => result
Deletes a message with a given MESSAGE-ID from the queue specified by QUEUE-URL.
[Function]
delete-queue queue-url
&key force-deletion =>
result
Deletes a queue specified by QUEUE-URL. If FORCE-DELETION is true, deletes the queue even if it contains messages.
[Function]
get-queue-attributes
queue-url &key attributes =>
result
Get attributes of the queue specified by QUEUE-URL. Returns an alist with attribute names (as keywords) and their values. ATTRIBUTES may be one of :all, :approximate-number-of-messages or :visibility-timeout. If left unspecified, it defaults to :all.
[Function]
list-queues
&optional queue-name-prefix =>
result
Returns the list of queues that currently exist. Note that even if there is only one queue, a list (with one element) will be returned. QUEUE-NAME-PREFIX, if supplied, indicates a prefix used to filter the list of queues.
[Function]
peek-message queue-url
message-id => result
Peeks at a message indicated by MESSAGE-ID from the queue specified by QUEUE-URL without locking the message. Returns a cons cell containing the message id and message body.
[Function]
receive-message queue-url
&key visibility-timeout
number-of-messages => result
Receive one or more message from the queue specified by QUEUE-URL. Returns a list of cons cells each containing the message id and message body. VISIBILITY-TIMEOUT, if supplied, overrides the default per-queue locking timeout. NUMBER-OF-MESSAGES indicates the number of messages that we wish returned and defaults to one. There are no guarantees as to how many messages will actually be returned.
[Function]
send-message queue-url
content => result
Places a message in the queue specified by QUEUE-URL. CONTENT is the message content, which may not exceed 256kB and is limited to a subset of Unicode characters (see Amazon SQS developer documentation for details). If necessary, it is the caller's responsibility to ASCII-encode the content.
[Function]
set-queue-attributes
queue-url &key visibility-timeout
=> result
Set attributes of the queue specified by QUEUE-URL. VISIBILITY-TIMEOUT must be specified, as this is the only attribute that can currently be set.
[Condition type]
sqs-api-error
Amazon SQS API error. Encapsulates an API error response from Amazon SQS. RESPONSE contains the entire XML of the response, while CODE and MESSAGE contain the error code and a human-readable message, respectively.
[Condition type]
sqs-error
General Amazon SQS error. All conditions signalled by CL-SQS are subclassed from this one.
[Condition type]
sqs-parameters-error
Amazon SQS parameters error. Indicates a problem with one or more call parameters that are checked locally, before making a request to Amazon SQS.
[Condition type]
sqs-response-error
Amazon SQS unexpected response error. This condition is signalled when the response from Amazon SQS web services does not match what we expected. It usually indicates a bug in the CL-SQS code or a major change in the Amazon SQS API (which is not supposed to happen).
Acknowledgments
This documentation was prepared with DOCUMENTATION-TEMPLATE. Initial versions of CL-SQS were inspired by the CL-S3 library, but no code is actually shared between them and the approach taken to interfacing with Amazon Web Services is quite different.