Merge lp:~rvb/gwacl/poller into lp:gwacl

[Raphaël Badin]

Add generic poller utility. Add a specialized poller to poll the Windows Azure server until an operation is completed.

The main change in this branch is the addition of the file poller.go (and the related tests) which adds a generic Poller interface and a generic method to actually perform the polling plus an specialized implementation for polling the Windows Azure server until a specific operation is completed.

A second branch will:
- change the asynchronous operations from managementapi.go so that they will return the corresponding operation id.
- update live_example_managementapi.go to wait for the completion of asynchronous operations.

This change was pre-imp'ed with Jeroen but instead of returning channels like we originally thought StartPolling would do, I decided to create a blocking method. It's then up to the caller to use goroutines if he does not want to block during the polling. This is ­— I think — a better design because it leaves it up to the caller to create and manage channels as he likes.

I've moved the test utilities rig*** in the test_helpers.go file because they are now used in many places.

Also, I changed the session's get/post/put so that they now return the full response instead of just the body. We need that in order to check the return status (and we will also need it to extract the operationID value from the headers).

[Jeroen T. Vermeulen (jtv)]

Please don't refer to a generic "the caller" as "she"! It's especially confusing because unlike "une prick," a caller is grammatically masculine.

English has a better way of dealing with indeterminate genders: use "they," with the corresponding plural verbs. Unlike other languages, English has no problem with switching conjugations halfway through a sentence for this purpose — "If the customer _has_ a complaint, remember to say that _they are_ right."

(Also, "wants not to block" is geek-speak. In real English you'd say "does not want to block," or perhaps "wants to avoid blocking.")

[Jeroen T. Vermeulen (jtv)]

I think I was wrong on one point, actually: "wants to not block" would be the correct geek-speak. :-)

[Jeroen T. Vermeulen (jtv)]

Oh, and ESPECIALLY don't arbitrarily switch genders for the same person¹. Did somebody make you a bet that it would set me off? :)

—
¹) With the appropriate exception for trans-gender individuals, of course.

[Raphaël Badin (rvb)]

Wording is fixed… can I haz code review? ;)

[Raphaël Badin (rvb)]

> Oh, and ESPECIALLY don't arbitrarily switch genders for the same person¹. Did
> somebody make you a bet that it would set me off? :)

Well, I guess I know which button to push if I want to set you off now :).

[Jeroen T. Vermeulen (jtv)]

Oh, no worries. Just about any button will do for that.

[Jeroen T. Vermeulen (jtv)]

You mentioned that you were taking this channel-less approach and I think it was the right choice.

Overall a long but good branch, except for one annoying detail that you'll find below.

.

Could you document Poller to set the right expectations with the reader? The "flyweight" approach in particular looks a bit confusing. My understanding is that the Poller gives you a response and then you need to ask that same Poller whether that response means that you're done... I think I understand why it's done that way (it allows for an immutable poller) but it would help to have it stated.

I like the separation between the Poller interface and the internal implementation. Exposing the x509Response doesn't really fit in though. My recollection is that we had meant that to be internal to gwacl, given the duplication with http.Response, and now x509Response is no longer exported. This part needs fixing, I think — though not necessarily in the same branch.

.

Well done for documenting the pointless panic at the end of StartPolling. I guess in the future the compiler will get smarter, detect that the loop never exits, and complain that the panic() is unreachable. The compiler giveth, and then the compiler taketh away.

.

On reflection, maybe StartPolling() isn't quite the right name, in that it implies that it won't do the actual polling.

.

Typo in the documentation for operationPoller: "A object."

By the way, I'm not sure if documentation for a type should also begin with its name.

.

The documentation for operationPoller.Poll() and operationPoller.IsDone() gets lost in trying to describe the implementation. Document what they mean to the caller, not how they do their work! As a caller, I really don't care whether Poll() issues a GET request or a HEAD request — gwacl's exact purpose is to hide that sort of thing from me. What I care about as a caller is primarily: that I need to call these methods in order to wait for my prior request to complete and secondarily: that it makes outgoing requests and that it blocks.

.

In operationPoller.IsDone(), I think I see one of those xml.Unmarshal() calls that need an error check.

.

I like the tests. Excellent comment in TestStartPollingRetries().

.

In TestStartOperationRetries, "InProgress" is misspelled as "InProgres" in a comment and "Succeeded" is misspelled twice as "Succeded" — which may be working just because it's consistent, but it's late for me.

.

Jeroen

review: Approve

[lp:~rvb/gwacl/poller]

63. By Raphaël Badin on 2013-03-27

Review comments.

[Raphaël Badin (rvb)]

Thanks for the review.

>
> Could you document Poller to set the right expectations with the reader? The
> "flyweight" approach in particular looks a bit confusing. My understanding is
> that the Poller gives you a response and then you need to ask that same Poller
> whether that response means that you're done... I think I understand why it's
> done that way (it allows for an immutable poller) but it would help to have it
> stated.

Added a comments.

> I like the separation between the Poller interface and the internal
> implementation. Exposing the x509Response doesn't really fit in though. My
> recollection is that we had meant that to be internal to gwacl, given the
> duplication with http.Response, and now x509Response is no longer exported.
> This part needs fixing, I think — though not necessarily in the same branch.

You're right, now that x509Response is not exposed, the method in the poller interface should not be exposed either. Same for startPolling which is more of an internal utility method used by more concrete implementations such as StartOperationPolling.

> On reflection, maybe StartPolling() isn't quite the right name, in that it
> implies that it won't do the actual polling.

Hum, I don't really have a better idea right now so I'll land this as is and we will see if we come up with a better name later.

> Typo in the documentation for operationPoller: "A object."

Fixed.

> The documentation for operationPoller.Poll() and operationPoller.IsDone() gets
> lost in trying to describe the implementation. Document what they mean to the
> caller, not how they do their work! As a caller, I really don't care whether
> Poll() issues a GET request or a HEAD request — gwacl's exact purpose is to
> hide that sort of thing from me. What I care about as a caller is primarily:
> that I need to call these methods in order to wait for my prior request to
> complete and secondarily: that it makes outgoing requests and that it blocks.

This is really internal stuff, no user will ever call these methods directly, hence the focus on explaining what the methods do internally.

> In operationPoller.IsDone(), I think I see one of those xml.Unmarshal() calls
> that need an error check.

Indeed, I've left it as is, we will fix this in another branch.

> In TestStartOperationRetries, "InProgress" is misspelled as "InProgres" in a
> comment and "Succeeded" is misspelled twice as "Succeded" — which may be
> working just because it's consistent, but it's late for me.

oops, fixed.

Thanks again for the review.

[lp:~rvb/gwacl/poller]

64. By Raphaël Badin on 2013-03-27

Merge trunk, fix conflicts.

[Julian Edwards (julian-edwards)]

On Wednesday 27 Mar 2013 14:09:17 you wrote:
> > Oh, and ESPECIALLY don't arbitrarily switch genders for the same person¹.
> > Did somebody make you a bet that it would set me off? :)
>
> Well, I guess I know which button to push if I want to set you off now :).

There are SO many to choose.

[Julian Edwards (julian-edwards)]

On Wednesday 27 Mar 2013 17:06:24 you wrote:
> > On reflection, maybe StartPolling() isn't quite the right name, in that it
> > implies that it won't do the actual polling.
>
> Hum, I don't really have a better idea right now so I'll land this as is and
> we will see if we come up with a better name later.

There is a certain school of thought that says this method should not even be
exported, and that the API should just block (with a timeout) until the async
operation completes.

[Jeroen T. Vermeulen (jtv)]

Yes, it is the fact that Poller is exported that made me think that it was to be part of gwacl's external API.

=== modified file 'managementapi.go'
--- managementapi.go	2013-03-26 06:50:50 +0000
+++ managementapi.go	2013-03-27 17:10:31 +0000
@@ -32,7 +32,7 @@
         return nil, err
     }
     hostedServices := HostedServiceDescriptorList{}
-    xml.Unmarshal(res, &hostedServices)
+    xml.Unmarshal(res.Body, &hostedServices)
     return hostedServices.HostedServices, nil
 }
 
@@ -44,7 +44,7 @@
         return nil, err
     }
     hostedService := HostedService{}
-    xml.Unmarshal(res, &hostedService)
+    xml.Unmarshal(res.Body, &hostedService)
     return &hostedService, nil
 }
 

=== modified file 'managementapi_test.go'
--- managementapi_test.go	2013-03-26 09:54:07 +0000
+++ managementapi_test.go	2013-03-27 17:10:31 +0000
@@ -48,12 +48,16 @@
     return &recordedRequests
 }
 
-// checkRequest asserts that the given slice contains one request, with the
+// checkOneRequest asserts that the given slice contains one request, with the
 // given characteristics.
-func checkRequest(c *C, recordedRequests *[]*x509Request, URL string, payload []byte, Method string) {
+func checkOneRequest(c *C, recordedRequests *[]*x509Request, URL string, payload []byte, Method string) {
     requests := *recordedRequests
     c.Assert(len(requests), Equals, 1)
     request := requests[0]
+    checkRequest(c, request, URL, payload, Method)
+}
+
+func checkRequest(c *C, request *x509Request, URL string, payload []byte, Method string) {
     c.Assert(request.URL, Equals, URL)
     c.Assert(string(request.Payload), Equals, string(payload))
     c.Assert(request.Method, Equals, Method)
@@ -61,33 +65,33 @@
 
 func (suite *managementAPISuite) TestListHostedServiceDescriptors(c *C) {
     api := suite.makeAPI(c)
-    recordedRequests := suite.setUpDispatcher()
+    recordedRequests := setUpDispatcher("operationID")
 
     _, err := api.ListHostedServiceDescriptors()
 
     c.Assert(err, IsNil)
     expectedURL := AZURE_URL + api.session.subscriptionId + "/services/hostedservices"
-    checkRequest(c, recordedRequests, expectedURL, []byte{}, "GET")
+    checkOneRequest(c, recordedRequests, expectedURL, []byte{}, "GET")
 }
 
 // TODO test that ListHostedServiceDescriptors parses the structures correctly
 
 func (suite *managementAPISuite) TestLoadHostedService(c *C) {
     api := suite.makeAPI(c)
-    recordedRequests := suite.setUpDispatcher()
+    recordedRequests := setUpDispatcher("operationID")
     serviceName := "serviceName"
     _, err := api.LoadHostedService(serviceName)
 
     c.Assert(err, IsNil)
     expectedURL := AZURE_URL + api.session.subscriptionId + "/services/hostedservices/" + serviceName + "?embed-detail=true"
-    checkRequest(c, recordedRequests, expectedURL, []byte{}, "GET")
+    checkOneRequest(c, recordedRequests, expectedURL, []byte{}, "GET")
 }
 
 // TODO test that TestLoadHostedService parses the structures correctly
 
 func (suite *managementAPISuite) TestAddHostedService(c *C) {
     api := suite.makeAPI(c)
-    recordedRequests := suite.setUpDispatcher()
+    recordedRequests := setUpDispatcher("operationID")
     createHostedService := NewCreateHostedServiceWithLocation("testName", "testLabel", "East US")
     err := api.AddHostedService(createHostedService)
 
@@ -95,23 +99,23 @@
     expectedURL := AZURE_URL + api.session.subscriptionId + "/services/hostedservices"
     expectedPayload, err := marshalXML(createHostedService)
     c.Assert(err, IsNil)
-    checkRequest(c, recordedRequests, expectedURL, expectedPayload, "POST")
+    checkOneRequest(c, recordedRequests, expectedURL, expectedPayload, "POST")
 }
 
 func (suite *managementAPISuite) TestDeleteHostedService(c *C) {
     api := suite.makeAPI(c)
-    recordedRequests := suite.setUpDispatcher()
+    recordedRequests := setUpDispatcher("operationID")
     hostedServiceName := "testName"
     err := api.DeleteHostedService(hostedServiceName)
 
     c.Assert(err, IsNil)
     expectedURL := AZURE_URL + api.session.subscriptionId + "/services/hostedservices/" + hostedServiceName
-    checkRequest(c, recordedRequests, expectedURL, []byte{}, "DELETE")
+    checkOneRequest(c, recordedRequests, expectedURL, []byte{}, "DELETE")
 }
 
 func (suite *managementAPISuite) TestAddDeployment(c *C) {
     api := suite.makeAPI(c)
-    recordedRequests := suite.setUpDispatcher()
+    recordedRequests := setUpDispatcher("operationID")
     serviceName := "serviceName"
     configurationSet := NewLinuxProvisioningConfiguration("testHostname12345", "test", "test123#@!", false)
     OSVirtualHardDisk := NewOSVirtualHardDisk("hostCaching", "diskLabel", "diskName", "http://mediaLink", "sourceImageName")
@@ -123,7 +127,7 @@
     expectedURL := AZURE_URL + api.session.subscriptionId + "/services/hostedservices/" + serviceName + "/deployments"
     expectedPayload, err := marshalXML(deployment)
     c.Assert(err, IsNil)
-    checkRequest(c, recordedRequests, expectedURL, expectedPayload, "POST")
+    checkOneRequest(c, recordedRequests, expectedURL, expectedPayload, "POST")
 }
 
 func (suite *managementAPISuite) TestAddStorageAccount(c *C) {
@@ -139,12 +143,12 @@
     expectedURL := AZURE_URL + api.session.subscriptionId + "/services/storageservices"
     expectedPayload, err := marshalXML(cssi)
     c.Assert(err, IsNil)
-    checkRequest(c, &recordedRequests, expectedURL, expectedPayload, "POST")
+    checkOneRequest(c, &recordedRequests, expectedURL, expectedPayload, "POST")
 }
 
 func (suite *managementAPISuite) TestPerformNodeOperation(c *C) {
     api := suite.makeAPI(c)
-    recordedRequests := suite.setUpDispatcher()
+    recordedRequests := setUpDispatcher("operationID")
     serviceName := "serviceName"
     deploymentName := "deploymentName"
     roleName := "roleName"
@@ -155,5 +159,5 @@
     expectedURL := AZURE_URL + api.session.subscriptionId + "/services/hostedservices/" + serviceName + "/deployments/" + deploymentName + "/roleinstances/" + roleName + "/Operations"
     expectedPayload, err := marshalXML(operation)
     c.Assert(err, IsNil)
-    checkRequest(c, recordedRequests, expectedURL, expectedPayload, "POST")
+    checkOneRequest(c, recordedRequests, expectedURL, expectedPayload, "POST")
 }

=== added file 'poller.go'
--- poller.go	1970-01-01 00:00:00 +0000
+++ poller.go	2013-03-27 17:10:31 +0000
@@ -0,0 +1,92 @@
+// Copyright 2013 Canonical Ltd.  This software is licensed under the
+// GNU Lesser General Public License version 3 (see the file COPYING).
+
+package gwacl
+
+import (
+    "encoding/xml"
+    "time"
+)
+
+// Generic poller interface/methods.
+
+// A Poller exposes two methods to query a remote server and decide when
+// the response given by the server means that the polling is finished. 
+type Poller interface {
+    poll() (*x509Response, error)
+    isDone(*x509Response) bool
+}
+
+// startPolling calls the poll() method of the given 'poller' object every
+// 'interval' until poller.isDone() return true.
+func startPolling(poller Poller, interval time.Duration) (*x509Response, error) {
+    // TODO: Add a timeout so that polling won't continue forever if isDone()
+    // always returns false.
+    ticker := time.Tick(interval)
+    for _ = range ticker {
+        response, err := poller.poll()
+        if err != nil {
+            return nil, err
+        }
+        if poller.isDone(response) {
+            return response, nil
+        }
+    }
+    // This code cannot be reached but Go insists on having a return or a panic
+    // statement at the end of this method.  Sigh.
+    panic("invalid poller state!")
+}
+
+// Operation poller structs/methods.
+
+// StartOperationPolling calls startPolling on the given arguments and converts
+// the returned object into an *Operation.
+func StartOperationPolling(poller Poller, interval time.Duration) (*Operation, error) {
+    response, err := startPolling(poller, interval)
+    if err != nil {
+        return nil, err
+    }
+    operation := Operation{}
+    xml.Unmarshal(response.Body, &operation)
+    return &operation, nil
+}
+
+// operationPoller is an object implementing the Poller interface, used to
+// poll the Window Azure server until the operation referenced by the given
+// operationID is completed.
+type operationPoller struct {
+    api         *ManagementAPI
+    operationID string
+}
+
+var _ Poller = &operationPoller{}
+
+// NewOperationPoller returns a poller object associated with the given
+// management API object and the given operationID.  It can track (by polling
+// the server) the status of the operation associated with the provided
+// operationID string.
+func NewOperationPoller(api *ManagementAPI, operationID string) Poller {
+    return operationPoller{api: api, operationID: operationID}
+}
+
+// Poll issues a blocking request to microsoft Azure to fetch the information
+// related to the operation associated with the poller.
+func (poller operationPoller) poll() (*x509Response, error) {
+    URI := "operations/" + poller.operationID
+    return poller.api.session.get(URI)
+}
+
+// IsDone returns true if the given response has a status code indicating
+// success and if the returned XML response corresponds to a valid Operation
+// with a status indicating that the operation is completed.
+func (poller operationPoller) isDone(response *x509Response) bool {
+    // TODO: Add a timeout so that polling won't continue forever if the
+    // server cannot be reached.
+    if response.StatusCode >= 200 && response.StatusCode < 300 {
+        operation := Operation{}
+        xml.Unmarshal(response.Body, &operation)
+        status := operation.Status
+        return (status != "" && status != InProgressOperationStatus)
+    }
+    return false
+}

=== added file 'poller_test.go'
--- poller_test.go	1970-01-01 00:00:00 +0000
+++ poller_test.go	2013-03-27 17:10:31 +0000
@@ -0,0 +1,187 @@
+// Copyright 2013 Canonical Ltd.  This software is licensed under the
+// GNU Lesser General Public License version 3 (see the file COPYING).
+
+package gwacl
+
+import (
+    "fmt"
+    . "launchpad.net/gocheck"
+    "launchpad.net/gwacl/dedent"
+    "net/http"
+    "time"
+)
+
+type pollerSuite struct{}
+
+var _ = Suite(&pollerSuite{})
+
+func (suite *pollerSuite) makeAPI(c *C) *ManagementAPI {
+    subscriptionId := "subscriptionId"
+    subscriptionId = subscriptionId
+    api, err := NewManagementAPI(subscriptionId, "certFile")
+    c.Assert(err, IsNil)
+    return api
+}
+
+// testPoller is a struct which implements the Poller interface.  It records
+// the number of calls to testPoller.Poll().
+type testPoller struct {
+    recordedPollCalls int
+    notDoneCalls      int
+    errorCalls        int
+}
+
+var testPollerResponse = x509Response{}
+var testPollerError = fmt.Errorf("Test error")
+
+// newTestPoller return a pointer to a testPoller object that will return
+// false when IsDone() will be called 'notDoneCalls' number of times and that
+// will error when Poll() will be called 'errorCalls' number of times.
+func newTestPoller(notDoneCalls int, errorCalls int) *testPoller {
+    return &testPoller{0, notDoneCalls, errorCalls}
+}
+
+func (poller *testPoller) poll() (*x509Response, error) {
+    if poller.errorCalls > 0 {
+        poller.errorCalls -= 1
+        return nil, testPollerError
+    }
+    poller.recordedPollCalls += 1
+    return &testPollerResponse, nil
+}
+
+func (poller *testPoller) isDone(response *x509Response) bool {
+    if poller.notDoneCalls == 0 {
+        return true
+    }
+    poller.notDoneCalls = poller.notDoneCalls - 1
+    return false
+}
+
+func (suite *pollerSuite) TeststartPollingReturnsError(c *C) {
+    poller := newTestPoller(0, 1)
+    response, err := startPolling(poller, time.Millisecond)
+
+    c.Assert(err, Equals, testPollerError)
+    c.Assert(response, IsNil)
+}
+
+func (suite *pollerSuite) TeststartPollingRetries(c *C) {
+    poller := newTestPoller(2, 0)
+    response, err := startPolling(poller, time.Millisecond)
+
+    c.Assert(err, IsNil)
+    c.Assert(response, Equals, &testPollerResponse)
+    // Poll() has been called 3 times: two calls for which IsDone() returned
+    // false and one for which IsDone() return true.
+    c.Assert(poller.recordedPollCalls, Equals, 3)
+}
+
+func (suite *pollerSuite) TestNewOperationPoller(c *C) {
+    api := suite.makeAPI(c)
+    operationID := "operationID"
+
+    poller := NewOperationPoller(api, operationID)
+
+    operationPollerInstance := poller.(operationPoller)
+    c.Check(operationPollerInstance.api, Equals, api)
+    c.Check(operationPollerInstance.operationID, Equals, operationID)
+}
+
+func (suite *pollerSuite) TestOperationPollerPoll(c *C) {
+    api := suite.makeAPI(c)
+    operationID := "operationID"
+    poller := NewOperationPoller(api, operationID)
+    recordedRequests := setUpDispatcher("operationID")
+
+    _, err := poller.poll()
+
+    c.Assert(err, IsNil)
+    expectedURL := AZURE_URL + api.session.subscriptionId + "/operations/" + operationID
+    checkOneRequest(c, recordedRequests, expectedURL, []byte{}, "GET")
+}
+
+var operationXMLTemplate = dedent.Dedent(`
+<?xml version="1.0" encoding="utf-8"?>
+  <Operation xmlns="http://schemas.microsoft.com/windowsazure">
+    <ID>bogus-request-id</ID>
+    <Status>%s</Status>
+  </Operation>
+`)
+
+func (suite *pollerSuite) TestOperationPollerIsDoneReturnsTrueIfOperationDone(c *C) {
+    poller := NewOperationPoller(suite.makeAPI(c), "operationID")
+    operationStatuses := []string{"Succeeded", "Failed"}
+    for _, operationStatus := range operationStatuses {
+        body := fmt.Sprintf(operationXMLTemplate, operationStatus)
+        response := x509Response{
+            Body:       []byte(body),
+            StatusCode: http.StatusOK,
+        }
+
+        isDone := poller.isDone(&response)
+        c.Assert(isDone, Equals, true)
+    }
+}
+
+func (suite *pollerSuite) TestOperationPollerIsDoneReturnsFalse(c *C) {
+    poller := NewOperationPoller(suite.makeAPI(c), "operationID")
+    notDoneResponses := []x509Response{
+        // 'InProgress' response.
+        x509Response{
+            Body:       []byte(fmt.Sprintf(operationXMLTemplate, "InProgress")),
+            StatusCode: http.StatusOK,
+        },
+        // Invalid XML content.
+        x509Response{
+            Body:       []byte("invalid XML"),
+            StatusCode: http.StatusOK,
+        },
+        // Error statuses.
+        x509Response{StatusCode: http.StatusNotFound},
+        x509Response{StatusCode: http.StatusBadRequest},
+        x509Response{StatusCode: http.StatusInternalServerError},
+    }
+    for _, response := range notDoneResponses {
+        isDone := poller.isDone(&response)
+        c.Assert(isDone, Equals, false)
+    }
+}
+
+func (suite *pollerSuite) TestStartOperationPollingRetries(c *C) {
+    // This is an end-to-end test of the operation poller; there is a certain
+    // amount of duplication with the unit tests for startPolling() but
+    // it's probably worth it to thoroughly test StartOperationPolling().
+
+    // Fake 2 responses in sequence: a 'InProgress' response and then a
+    // 'Succeeded' response. 
+    firstResponse := DispatcherResponse{
+        response: &x509Response{
+            Body:       []byte(fmt.Sprintf(operationXMLTemplate, "InProgress")),
+            StatusCode: http.StatusOK,
+        },
+        errorObject: nil}
+    secondResponse := DispatcherResponse{
+        response: &x509Response{
+            Body:       []byte(fmt.Sprintf(operationXMLTemplate, "Succeeded")),
+            StatusCode: http.StatusOK,
+        },
+        errorObject: nil}
+    responses := []DispatcherResponse{firstResponse, secondResponse}
+    rigPreparedResponseDispatcher(responses)
+    recordedRequests := make([]*x509Request, 0)
+    rigRecordingDispatcher(&recordedRequests)
+
+    // Setup poller and start it.
+    operationID := "operationID"
+    poller := NewOperationPoller(suite.makeAPI(c), operationID)
+    response, err := startPolling(poller, time.Millisecond)
+
+    c.Assert(err, IsNil)
+    c.Assert(response, Equals, secondResponse.response)
+    operationPollerInstance := poller.(operationPoller)
+    expectedURL := AZURE_URL + operationPollerInstance.api.session.subscriptionId + "/operations/" + operationID
+    c.Assert(len(recordedRequests), Equals, 2)
+    checkRequest(c, recordedRequests[0], expectedURL, []byte{}, "GET")
+    checkRequest(c, recordedRequests[1], expectedURL, []byte{}, "GET")
+}

=== modified file 'test_helpers.go'
--- test_helpers.go	2013-03-21 02:14:39 +0000
+++ test_helpers.go	2013-03-27 17:10:31 +0000
@@ -6,6 +6,7 @@
 import (
     "fmt"
     "math/rand"
+    "net/http"
     "strings"
     "time"
 )
@@ -181,6 +182,69 @@
         ExtendedProperties:    ExtendedProperties}
 }
 
+// rigRecordingDispatcher sets up a request dispatcher that records incoming
+// requests by appending them to *record.  It returns the result of whatever
+// dispatcher was already active.
+// If you also want the dispatcher to return a particular result, rig it for
+// that result first (using one of the other rig...Dispatcher functions) and
+// then chain the recording dispatcher in front of it.
+func rigRecordingDispatcher(record *[]*x509Request) {
+    previousDispatcher := _X509Dispatcher
+    _X509Dispatcher = func(session *x509Session, request *x509Request) (*x509Response, error) {
+        *record = append(*record, request)
+        return previousDispatcher(session, request)
+    }
+}
+
+// rigFixedResponseDispatcher sets up a request dispatcher that always returns
+// a prepared response.
+func rigFixedResponseDispatcher(response *x509Response) {
+    _X509Dispatcher = func(*x509Session, *x509Request) (*x509Response, error) {
+        return response, nil
+    }
+}
+
+// rigFailingDispatcher sets up a request dispatcher that returns a given
+// error.
+func rigFailingDispatcher(failure error) {
+    _X509Dispatcher = func(*x509Session, *x509Request) (*x509Response, error) {
+        return nil, failure
+    }
+}
+
+type DispatcherResponse struct {
+    response    *x509Response
+    errorObject error
+}
+
+// rigPreparedResponseDispatcher sets up a request dispatcher that all the provided
+// reponses, one after the other each time the dispatcher is called.
+func rigPreparedResponseDispatcher(responses []DispatcherResponse) {
+    index := 0
+    _X509Dispatcher = func(*x509Session, *x509Request) (*x509Response, error) {
+        response := responses[index]
+        index += 1
+        return response.response, response.errorObject
+    }
+}
+
+// setUpDispatcher sets up a request dispatcher that:
+// - records requests
+// - returns empty responses
+func setUpDispatcher(operationID string) *[]*x509Request {
+    header := http.Header{}
+    header.Set("X-Ms-Request-Id", operationID)
+    fixedResponse := x509Response{
+        StatusCode: http.StatusOK,
+        Body:       []byte{},
+        Header:     header,
+    }
+    rigFixedResponseDispatcher(&fixedResponse)
+    recordedRequests := make([]*x509Request, 0)
+    rigRecordingDispatcher(&recordedRequests)
+    return &recordedRequests
+}
+
 func init() {
     // Staggeringly, rand will produce the same numbers from the start of
     // program invocation unless you seed it ...

=== modified file 'x509session.go'
--- x509session.go	2013-03-27 07:16:45 +0000
+++ x509session.go	2013-03-27 17:10:31 +0000
@@ -43,7 +43,7 @@
 // It returns the response body and/or an error.  If the error is a
 // ServerError, the returned body will be the one received from the server.
 // For any other kind of error, the returned body will be nil.
-func (session *x509Session) get(url string) ([]byte, error) {
+func (session *x509Session) get(url string) (*x509Response, error) {
     fullUrl := composeURL(url, session.subscriptionId)
     request := newX509RequestGET(fullUrl)
     response, err := _X509Dispatcher(session, request)
@@ -51,14 +51,14 @@
         return nil, err
     }
     err = session.getServerError(response.StatusCode, response.Body, "GET request failed")
-    return response.Body, err
+    return response, err
 }
 
 // post performs a POST request to the Azure management API.
 // It returns the response body and/or an error.  If the error is a
 // ServerError, the returned body will be the one received from the server.
 // For any other kind of error, the returned body will be nil.
-func (session *x509Session) post(url string, body []byte, contentType string) ([]byte, error) {
+func (session *x509Session) post(url string, body []byte, contentType string) (*x509Response, error) {
     fullUrl := composeURL(url, session.subscriptionId)
     request := newX509RequestPOST(fullUrl, body, contentType)
     response, err := _X509Dispatcher(session, request)
@@ -66,7 +66,7 @@
         return nil, err
     }
     err = session.getServerError(response.StatusCode, response.Body, "POST request failed")
-    return response.Body, err
+    return response, err
 }
 
 // delete performs a DELETE request to the Azure management API.
@@ -81,12 +81,12 @@
 }
 
 // put performs a PUT request to the Azure management API.
-func (session *x509Session) put(url string, body []byte) error {
+func (session *x509Session) put(url string, body []byte) (*x509Response, error) {
     fullUrl := composeURL(url, session.subscriptionId)
     request := newX509RequestPUT(fullUrl, body)
     response, err := _X509Dispatcher(session, request)
     if err != nil {
-        return err
+        return nil, err
     }
-    return session.getServerError(response.StatusCode, response.Body, "POST request failed")
+    return response, session.getServerError(response.StatusCode, response.Body, "POST request failed")
 }

=== modified file 'x509session_test.go'
--- x509session_test.go	2013-03-27 16:34:04 +0000
+++ x509session_test.go	2013-03-27 17:10:31 +0000
@@ -44,36 +44,6 @@
 
 var _ = Suite(&x509SessionSuite{})
 
-// rigRecordingDispatcher sets up a request dispatcher that records incoming
-// requests by appending them to *record.  It returns the result of whatever
-// dispatcher was already active.
-// If you also want the dispatcher to return a particular result, rig it for
-// that result first (using one of the other rig...Dispatcher functions) and
-// then chain the recording dispatcher in front of it.
-func rigRecordingDispatcher(record *[]*x509Request) {
-    previousDispatcher := _X509Dispatcher
-    _X509Dispatcher = func(session *x509Session, request *x509Request) (*x509Response, error) {
-        *record = append(*record, request)
-        return previousDispatcher(session, request)
-    }
-}
-
-// rigFixedResponseDispatcher sets up a request dispatcher that always returns
-// a prepared response.
-func rigFixedResponseDispatcher(response *x509Response) {
-    _X509Dispatcher = func(*x509Session, *x509Request) (*x509Response, error) {
-        return response, nil
-    }
-}
-
-// rigFailingDispatcher sets up a request dispatcher that returns a given
-// error.
-func rigFailingDispatcher(failure error) {
-    _X509Dispatcher = func(*x509Session, *x509Request) (*x509Response, error) {
-        return nil, failure
-    }
-}
-
 // Create a cert and pem file in a temporary dir in /tmp and return the
 // names of the files.  The caller is responsible for cleaning up the files.
 func makeX509Certificate() (string, string) {
@@ -198,14 +168,14 @@
     recordedRequests := make([]*x509Request, 0)
     rigRecordingDispatcher(&recordedRequests)
 
-    receivedBody, err := session.get(uri)
+    receivedResponse, err := session.get(uri)
     c.Assert(err, IsNil)
 
     c.Assert(len(recordedRequests), Equals, 1)
     request := recordedRequests[0]
     c.Check(request.URL, Equals, AZURE_URL+subscriptionID+"/"+uri)
     c.Check(request.Method, Equals, "GET")
-    c.Check(receivedBody, DeepEquals, fixedResponse.Body)
+    c.Check(*receivedResponse, DeepEquals, fixedResponse)
 }
 
 func (suite *x509SessionSuite) TestGetReportsClientSideError(c *C) {
@@ -228,12 +198,12 @@
     }
     rigFixedResponseDispatcher(&fixedResponse)
 
-    body, err := session.get("/fail")
+    response, err := session.get("/fail")
     c.Assert(err, NotNil)
 
     serverError := err.(*ServerError)
     c.Check(serverError.StatusCode(), Equals, fixedResponse.StatusCode)
-    c.Check(body, DeepEquals, fixedResponse.Body)
+    c.Check(*response, DeepEquals, fixedResponse)
 }
 
 func (suite *x509SessionSuite) TestPostIssuesRequest(c *C) {
@@ -252,7 +222,7 @@
     recordedRequests := make([]*x509Request, 0)
     rigRecordingDispatcher(&recordedRequests)
 
-    receivedBody, err := session.post(uri, requestBody, requestContentType)
+    receivedResponse, err := session.post(uri, requestBody, requestContentType)
     c.Assert(err, IsNil)
 
     c.Assert(len(recordedRequests), Equals, 1)
@@ -261,7 +231,7 @@
     c.Check(request.Method, Equals, "POST")
     c.Check(request.ContentType, Equals, requestContentType)
     c.Check(request.Payload, DeepEquals, requestBody)
-    c.Check(receivedBody, DeepEquals, fixedResponse.Body)
+    c.Check(*receivedResponse, DeepEquals, fixedResponse)
 }
 
 func (suite *x509SessionSuite) TestPostReportsClientSideError(c *C) {
@@ -284,12 +254,12 @@
     }
     rigFixedResponseDispatcher(&fixedResponse)
 
-    body, err := session.post("/fail", []byte("request body"), "contentType")
+    reponse, err := session.post("/fail", []byte("request body"), "contentType")
     c.Assert(err, NotNil)
 
     serverError := err.(*ServerError)
     c.Check(serverError.StatusCode(), Equals, fixedResponse.StatusCode)
-    c.Check(body, DeepEquals, fixedResponse.Body)
+    c.Check(*reponse, DeepEquals, fixedResponse)
 }
 
 func (suite *x509SessionSuite) TestDeleteIssuesRequest(c *C) {
@@ -326,7 +296,7 @@
     recordedRequests := make([]*x509Request, 0)
     rigRecordingDispatcher(&recordedRequests)
 
-    err = session.put(uri, requestBody)
+    _, err = session.put(uri, requestBody)
     c.Assert(err, IsNil)
 
     c.Assert(len(recordedRequests), Equals, 1)

=== modified file 'xmlobjects.go'
--- xmlobjects.go	2013-03-27 07:16:45 +0000
+++ xmlobjects.go	2013-03-27 17:10:31 +0000
@@ -520,3 +520,17 @@
 func (g *GetBlockList) Deserialize(data []byte) error {
     return xml.Unmarshal(data, g)
 }
+
+//
+// Operation Services bits
+//
+
+var InProgressOperationStatus = "InProgress"
+
+type Operation struct {
+    ID             string `xml:"ID"`
+    Status         string `xml:"Status"`
+    HttpStatusCode int    `xml:"HttpStatusCode"`
+    ErrorCode      string `xml:"Error>Code"`
+    ErrorMessage   string `xml:"Error>Message"`
+}