Open Stack

Hey everyone,

So I've been working on the transport layer today and wanted to run some thing past everyone to make sure we're all on the same page. There's no new major new work: just tweeking some existing stuff and moving functionality into new files where I thought it would make things clearer.

1. Minor updates `ClientInterface`

I agree with Matt: we need to keep this interface as simple as possible for new client classes to implement. There's two discrete pieces of functionality the interface should care about: requests and configuration. Here's an outline of what I thought might work:

https://gist.github.com/jamiehannaford/01bbf366f5f3da07bbcd

I tried to keep things as simple as possible - can people lend me their thoughts on it?

One of the main differences with the current version is that it separates out the process of creating a request from sending it. Right now we do it in one method, which is disadvantageous for two reasons:

1. It prevents users from modifying the Request object before sending it. Matt raised a very good point that you can pass in extra headers, etc. into the signature itself - but what I'm talking about is things like event subscribers. In the lifecycle of a cURL transaction (a Request being created, prepared, and sent; a response being parsed, etc.) different events are emitted. These events are incredibly useful and empowering for end-users because they enable people to add in their own custom logic to processes which are usually unavailable (unless you actually extend the SDK code). By having a "createRequest" method that actually returns a Request rather than just sending it, we're allowing users to add their own subscribers. Here are a few use-cases: a user might want to add a subscriber which logs everything for that 1 request; a user might want to use a subscriber to handle exceptions differently for that 1 request; a user might want to retry the Request if a particular status code is returned, etc.

2. Most common HTTP frameworks, like Guzzle and ZF2, use these two methods ("createRequest" and "send"). It makes sense to stick with convention so end-users and contributors are not confused.


2. Moving Guzzle stuff to a sub-directory

Right now we're using Guzzle by default, but we also want to support the ability for users to inject their own HTTP client in. So to make this clearer, I've moved Guzzle-specific files to their own "Guzzle" sub-directory (under the OpenStack\Common\Transport\Guzzle namespace). I've also changed the "GuzzleClient" classname to "GuzzleAdapter" because it's actually adapting an existing client, not serving as one. All it's doing is wrapping Guzzle and implementing our standard interface - so I wanted to make that clearer and avoid confusion.


3. HTTP exceptions

I also discovered a really cool way to handle exceptions. Right now, we're throwing exceptions in the adapter - which adds a lot of exception-specific logic to a base class. So instead, I copied all of this existing logic to a new "RequestException" class. All the GuzzleClient/GuzzleAdapter needs to do is call RequestException::create($request, $response) and all of the logic for finding the right class for the right HTTP status code is determined inside RequestException like this:

https://gist.github.com/jamiehannaford/0a085d4b1507308b0190

Another thing I wanted to do is make it easier for devs to debug the problem once an exception is thrown - so I made the Request and Response objects (for a failed request) available in the exception. So instead of printing out a generic message, we also allow them the ability to retrieve the offending request/response with $e->getRequest() and $e->getResponse()

---

That's about it, basically :)

Does anybody have any questions or concerns with any of this?

Jamie



Jamie Hannaford
Software Developer III - CH     [experience Fanatical Support]

Tel:    +41434303908
Mob:    +41791009767
        [Rackspace]



Rackspace International GmbH a company registered in the Canton of Zurich, Switzerland (company identification number CH-020.4.047.077-1) whose registered office is at Pfingstweidstrasse 60, 8005 Zurich, Switzerland. Rackspace International GmbH privacy policy can be viewed at www.rackspace.co.uk/legal/swiss-privacy-policy
-
Rackspace Hosting Australia PTY LTD a company registered in the state of Victoria, Australia (company registered number ACN 153 275 524) whose registered office is at Suite 3, Level 7, 210 George Street, Sydney, NSW 2000, Australia. Rackspace Hosting Australia PTY LTD privacy policy can be viewed at www.rackspace.com.au/company/legal-privacy-statement.php
-
Rackspace US, Inc, 5000 Walzem Road, San Antonio, Texas 78218, United States of America
Rackspace US, Inc privacy policy can be viewed at www.rackspace.com/information/legal/privacystatement
-
Rackspace Limited is a company registered in England & Wales (company registered number 03897010) whose registered office is at 5 Millington Road, Hyde Park Hayes, Middlesex UB3 4AZ.
Rackspace Limited privacy policy can be viewed at www.rackspace.co.uk/legal/privacy-policy
-
Rackspace Benelux B.V. is a company registered in the Netherlands (company KvK nummer 34276327) whose registered office is at Teleportboulevard 110, 1043 EJ Amsterdam.
Rackspace Benelux B.V privacy policy can be viewed at www.rackspace.nl/juridisch/privacy-policy
-
Rackspace Asia Limited is a company registered in Hong Kong (Company no: 1211294) whose registered office is at 9/F, Cambridge House, Taikoo Place, 979 King's Road, Quarry Bay, Hong Kong.
Rackspace Asia Limited privacy policy can be viewed at www.rackspace.com.hk/company/legal-privacy-statement.php
-
This e-mail message (including any attachments or embedded documents) is intended for the exclusive and confidential use of the individual or entity to which this message is addressed, and unless otherwise expressly indicated, is confidential and privileged information of Rackspace. Any dissemination, distribution or copying of the enclosed material is prohibited. If you receive this transmission in error, please notify us immediately by e-mail at abuse at rackspace.com and delete the original message. Your cooperation is appreciated.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140430/84b77474/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image1133a4.JPG
Type: image/jpeg
Size: 3124 bytes
Desc: image1133a4.JPG
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140430/84b77474/attachment.jpe>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image52edff.JPG
Type: image/jpeg
Size: 990 bytes
Desc: image52edff.JPG
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140430/84b77474/attachment-0001.jpe>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image2b0bf6.JPG
Type: image/jpeg
Size: 6844 bytes
Desc: image2b0bf6.JPG
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140430/84b77474/attachment-0002.jpe>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: imagec2ddd4.JPG
Type: image/jpeg
Size: 1074 bytes
Desc: imagec2ddd4.JPG
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140430/84b77474/attachment-0003.jpe>