1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
|
==================================================
Hacking in GWACL (Go Windows Azure Client Library)
==================================================
(this doc is a huge WIP)
Submitting changes
------------------
`GWACL`_ is hosted on Launchpad using `Bazaar`_. Submitting a change
requires you to create a merge proposal against the trunk branch and a
core committer will then review the branch. Once the branch is accepted,
it will be landed by the reviewer.
All branch submissions must be formatted using ``make format``. They must
also have a successful test run with ``make check``. New features must
always be accompanied by new tests.
.. _GWACL: https://launchpad.net/gwacl
.. _Bazaar: http://bazaar.canonical.com/
Prerequisites
-------------
The code that communicates with Azure's management API uses *libcurl*, through
a Go language binding called *go-curl*. You need to install the libcurl
headers for your OS. On Ubuntu this is::
sudo apt-get install libcurl4-openssl-dev
If you didn't ``go get`` gwacl you may also need to install go-curl::
go get github.com/andelf/go-curl
On Ubuntu 12.10 at least, you specifically need the given version of libcurl.
With other versions you will receive unexpected "403" HTTP status codes
("Forbidden") from the Azure server.
Why use libcurl? At the time of writing, Go's built-in http package does not
support TLS renegotiation. We find that Azure forces such a renegotiation
when we access the management API. The use of libcurl is embedded so that
future implementations can swap it out for a different http library without
breaking compatibility.
API philosophy
--------------
API functions in the library should take a single struct parameter, which
itself contains one or more parameters. Existing functions that do not follow
this rule are historic and should not be copied.
This brings several advantages::
1. Keyword parameters improve callsite readability.
2. It allows for parameters to be defaulted if not supplied.
3. It's much easier to change the API later without breaking existing
code, it just needs re-compiling in the case where you add new,
optional, parameters.
|