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
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
==================
Technical workbook
==================
Provider conventions
====================
The conventions described in this section must be followed by any provider implementation.
Contract of a Lexicon record
----------------------------
A Lexicon record is the internal representation of a DNS entry fetched or pushed to a DNS provider API.
These records are JSON objects that **must** follows the given contract.
Required fields
~~~~~~~~~~~~~~~
- **name** Clients should provide FQDN. Providers should handle both
FQDN and relative names.
- **ttl** Reasonable default is 6 hours since it’s supported by most
services. Any service that does not support this must be explicitly
mentioned somewhere.
- **record** All provider/API records must be translated to the
following format:
Example of a Lexicon record
~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
{
'id': string, // optional, provider specified unique id. Clients to treat this as opaque.
'type': string, // upper case, valid record type. eg. A, CNAME, TXT
'name': string, // lowercase, FQDN. eg. test.record.example.com
'ttl': integer, // positive integer, in seconds. eg. 3600
'content': string, //double quoted/escaped values should be unescaped. eg. "\"TXT content\"" should become "TXT content"
'options': {
'mx': { // MX options
'priority': integer
}
}
}
DNS operations
--------------
A Lexicon provider will have to make operations against a DNS provider API.
Here are the 5 possible operations, and the behavior each operation **must** follow.
authenticate
~~~~~~~~~~~~
- **Normal Behavior** Execute all required operations to authenticate against the provider API, then
retrieves the identifier of the domain and assign it to the ``self.domain_id`` property of the
``Provider`` instance.
- **Authentication failure** In case of authentication failure, the method **must** raise a
``lexicon.exceptions.AuthenticationError`` exception and break the flow.
create_record
~~~~~~~~~~~~~
- **Normal Behavior** Create a new DNS record. Return a boolean
``True`` if successful.
- **If Record Already Exists** Do nothing. **DO NOT** throw exception.
- **TTL** If not specified or set to ``0``, use reasonable default.
- **Record Sets** If service supports record sets, create new record
set or append value to existing record set as required.
list_record
~~~~~~~~~~~
- **Normal Behaviour** List all records. If filters are provided, send
to the API if possible, else apply filter locally. Return value
should be a list of records.
- **Record Sets** Ungroup record sets into individual records. Eg: If a
record set contains 3 values, provider ungroup them into 3 different
records.
- **Linked Records** For services that support some form of linked
record, do not resolve, treat as CNAME.
update_record
~~~~~~~~~~~~~
- **Normal Behaviour** Update a record. Record to be updated can be
specified by providing id OR name, type and content. Return a boolean
``True`` if successful.
- **Record Sets** If matched record is part of a record set, only
update the record that matches. Update the record set so that records
other than the matched one are unmodified.
- **TTL**
- If not specified, do not modify ttl.
- If set to ``0``, reset to reasonable default.
- **No Match** Throw exception?
delete_record
~~~~~~~~~~~~~
- **Normal Behaviour** Remove a record. Record to be deleted can be
specified by providing id OR name, type and content. Return a boolean
``True`` if successful.
- **Record sets** Remove only the record that matches all the filters.
- If content is not specified, remove the record set.
- If length of record set becomes 0 after removing record, remove
the record set.
- Otherwise, remove only the value that matches and leave other
records as-is.
- **No Match** Do nothing. **DO NOT** throw exception
Code documentation
==================
This section describes the public API of Lexicon code (classes, methods, functions) useful
to implement a new provider, or to interface Lexicon as a library to another project.
Module `lexicon.client`
-----------------------
.. automodule:: lexicon.client
:members:
Module `lexicon.interfaces`
---------------------------
.. automodule:: lexicon.interfaces
:members:
Module `lexicon.config`
-----------------------
.. automodule:: lexicon.config
:members:
Module `lexicon.exceptions`
---------------------------
.. automodule:: lexicon.exceptions
:members:
|
