aws

README

BREAKAGE WARNING!
=================
  The API is going under some substantial cleanups;  If you are building from sources prior to Jun 20, 2011,
you will likely find near-zero one-one compatibility.
  - Generally, the new API's are applied to SQS, S3 and SDB (in progress)
  - Check godoc for the new structures & shapes.
  - The tools have been aggregated into a single built tool (in progress)

  Some key functions are not yet implemented (ACL's, subresources), 
and most of it is not yet thoroughly tested outside the direct 
paths required for the command line tool.

  For quick usage examples, see {elb,s3,simpledb,sqs}/util/*.go.  The tools are 
fully capable of basic administration of ELB, S3, SQS, and SimpleDB resources, but 
are intended primarily for testing and API usage examples.

  This package should build/goinstall on its own, but to make use of the sub-modules,
you will need to run 'make modules modules_install'.  (If anyone can submit a patch
to allow goinstall to do the entire project, it will be gladly accepted!)

Bugs/Notes
==========
 - All the core modules maintain a persistant connection to the service endpoint
 - S3 doesn't currently follow redirects for puts
 - NO api's automatically retry, it is left to the caller to retry if so desired.
 - Errors are not consistant across all modules/calls, work is ongoing to fix this.
 - There are a number of issues related to Go's XML parsing that have made
full implementation potentially buggy.
 - Most basic commands/operations are available, but we do not currently support
setting ACL's or IAM (directly). 


Alternatives (let me know if I miss any)
========================================
  goamz - https://wiki.ubuntu.com/goamz - seems to have much more complete
ec2 support, and s3

Documentation

Index

• Constants
• Variables
• func Canonicalize(req *http.Request) (out string, err os.Error)
• func CanonicalizeS3(req *http.Request) (out string, err os.Error)
• func CodeToError(i int) (err os.Error)
• func NewRequest(url *http.URL, method string, hdrs http.Header, params http.Values) (req *http.Request)
• func SortedEscape(v http.Values) (out string)
• func URLDialer(u *http.URL, conf *tls.Config) (f func() (c net.Conn, err os.Error))
• type Conn
  • func NewConn(d Dialer) *Conn
  • func (self *Conn) Close() (err os.Error)
  • func (self *Conn) Request(req *http.Request) (resp *http.Response, err os.Error)
• type Dialer
• type ReusableConn
  • func NewReusableConnection(d Dialer) (c *ReusableConn)
  • func (self *ReusableConn) Close() (err os.Error)
  • func (self *ReusableConn) Dial() (err os.Error)
  • func (self *ReusableConn) LocalAddr() (a net.Addr)
  • func (self *ReusableConn) Read(in []byte) (n int, err os.Error)
  • func (self *ReusableConn) RemoteAddr() (a net.Addr)
  • func (self *ReusableConn) SetReadTimeout(t int64) (err os.Error)
  • func (self *ReusableConn) SetTimeout(t int64) (err os.Error)
  • func (self *ReusableConn) SetWriteTimeout(t int64) (err os.Error)
  • func (self *ReusableConn) Write(out []byte) (n int, err os.Error)
• type Signer
  • func NewSigner(akid, sak string) *Signer
  • func (self *Signer) SignBytes(h crypto.Hash, buff []byte) (sig []byte, err os.Error)
  • func (self *Signer) SignEncoded(h crypto.Hash, s string, e *base64.Encoding) (out []byte, err os.Error)
  • func (self *Signer) SignRequestV1(req *http.Request, canon func(*http.Request) (string, os.Error), exp int64) (err os.Error)
  • func (self *Signer) SignRequestV2(req *http.Request, canon func(*http.Request) (string, os.Error), ...) (err os.Error)
  • func (self *Signer) SignString(h crypto.Hash, s string) (os string, err os.Error)

Constants

const (
	DEFAULT_SIGNATURE_VERSION = "2"
	DEFAULT_SIGNATURE_METHOD  = "HmacSHA256"
)

Variables

var ErrUnderlyingNotconnected = os.NewError("Underlying socket is not connected")

var ErrorConflicts os.Error = os.NewError("Conflicts with another resources")

var ErrorForbidden os.Error = os.NewError("Access denied")

var ErrorNotFound os.Error = os.NewError("Not found")

var ErrorUnexpectedResponse os.Error = os.NewError("Unexpected response code")

var ISO8601TimestampFormat = "2006-01-02T15:04:05Z"

var SQSTimestampFormat = "2006-01-02T15:04:05MST"

Functions

func Canonicalize

func Canonicalize(req *http.Request) (out string, err os.Error)

Generates the canonical string-to-sign for (most) AWS services. You shouldn't need to use this directly.

func CanonicalizeS3

func CanonicalizeS3(req *http.Request) (out string, err os.Error)

Generates the canonical string-to-sign for S3 services. You shouldn't need to use this directly unless you're pre-signing URL's.

func CodeToError

func CodeToError(i int) (err os.Error)

func NewRequest

func NewRequest(url *http.URL, method string, hdrs http.Header, params http.Values) (req *http.Request)

Constructs a basic http.Request based off of a fully-qualified URL

func SortedEscape

func SortedEscape(v http.Values) (out string)

(2011-06-21) - The standard go http.Values.Escape works properly for SQS and S3, but it should be noted that at least SDB requiers more to be escaped than is officially standard.

Sorted Escape also sorts the keys before joining them (needed for canonicalization).

func URLDialer

func URLDialer(u *http.URL, conf *tls.Config) (f func() (c net.Conn, err os.Error))

A generic Dialer to handle both TLS and non TLS http connections.

Types

type Conn

type Conn struct {
	// contains filtered or unexported fields
}

The conn structure represents a 'semi detached' http-client It handles redialing & reconnecting on connection errors.

func NewConn

func NewConn(d Dialer) *Conn

Creates a new connection with the specified dialer function.

func (*Conn) Close

func (self *Conn) Close() (err os.Error)

Closes the underlying connection

NB: if you re-use the connection after this, it will be redialed.

func (*Conn) Request

func (self *Conn) Request(req *http.Request) (resp *http.Response, err os.Error)

Write a request and read the response; This function will also fix-up req.Form for 'GET's

type Dialer

type Dialer func() (net.Conn, os.Error)

A Dialer is usually a closuer that is pre-configured to the callers tastes.

(see URLDialer for an example/default generator)

type ReusableConn

type ReusableConn struct {
	// contains filtered or unexported fields
}

A Reusable conn is a syncronized structure around a Dialer / net.Conn pair. All net.Conn calls are wrapped around the underlying structure. Errors are bubbled up, and trigger closure of the underlying socket (to be reopened on the next call)

func NewReusableConnection

func NewReusableConnection(d Dialer) (c *ReusableConn)

Create a new reusable connection with a sepcific dialer.

func (*ReusableConn) Close

func (self *ReusableConn) Close() (err os.Error)

Unlike close on a traditional socket, no error is raised if you close a closed (nil) connection.

func (*ReusableConn) Dial

func (self *ReusableConn) Dial() (err os.Error)

Dial is idempotent, and safe to call;

func (*ReusableConn) LocalAddr

func (self *ReusableConn) LocalAddr() (a net.Addr)

See RemoteAddr for notes.

func (*ReusableConn) Read

func (self *ReusableConn) Read(in []byte) (n int, err os.Error)

Read from the underlying connection, triggering a dial if needed. NB: For the expected case (HTTP), this shouldn't happen before the first Write.

func (*ReusableConn) RemoteAddr

func (self *ReusableConn) RemoteAddr() (a net.Addr)

TODO: What's an appropriate responsde when we're not connected? ATM, we return whatever the other side says, or the nil net.Addr.

func (*ReusableConn) SetReadTimeout

func (self *ReusableConn) SetReadTimeout(t int64) (err os.Error)

Sets the read timeout on the underlying socket, as well as an internal flag for any future re-opened connections.

func (*ReusableConn) SetTimeout

func (self *ReusableConn) SetTimeout(t int64) (err os.Error)

Conveinience function for Set(read|write)timeout

func (*ReusableConn) SetWriteTimeout

func (self *ReusableConn) SetWriteTimeout(t int64) (err os.Error)

Sets the write timeout on the underlying socket, as well as an internal flag for any future re-opened connections.

func (*ReusableConn) Write

func (self *ReusableConn) Write(out []byte) (n int, err os.Error)

Write to the underlying connection, triggering a dial if needed.

type Signer

type Signer struct {
	AccessKey string
	// contains filtered or unexported fields
}

A signer simply holds the access & secret access keys necessary for aws, and proivides helper functions to assist in generating an appropriate signature.

func NewSigner

func NewSigner(akid, sak string) *Signer

func (*Signer) SignBytes

func (self *Signer) SignBytes(h crypto.Hash, buff []byte) (sig []byte, err os.Error)

the core function of the Signer, generates the raw hmac of he bytes.

func (*Signer) SignEncoded

func (self *Signer) SignEncoded(h crypto.Hash, s string, e *base64.Encoding) (out []byte, err os.Error)

SignBytes, but will base64 encode based on the specified encoder.

func (*Signer) SignRequestV1

func (self *Signer) SignRequestV1(req *http.Request, canon func(*http.Request) (string, os.Error), exp int64) (err os.Error)

Used exclusively by S3 to the best of my knowledge...

func (*Signer) SignRequestV2

func (self *Signer) SignRequestV2(req *http.Request, canon func(*http.Request) (string, os.Error), api_ver string, exp int64) (err os.Error)

The V2 denotes amazon signing version 2, not version 2 of this particular function... V2 is used by all services but S3; Note, some services vary in their exact implementation of escaping w/r/t signatures, so it is recommended you use this function.

Final note: if exp is set to 0, a Timestamp will be used, otherwise an expiration.

func (*Signer) SignString

func (self *Signer) SignString(h crypto.Hash, s string) (os string, err os.Error)

Same as SignBytes, but with strings.