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
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
# pyOuroboros
> a Python API for the Ouroboros recursive network prototype
## Dependencies
pyOuroboros requires <a href="https://ouroboros.rocks">Ouroboros</a>
to be installed
## Installation
To build and install PyOuroboros:
```shell
./setup.py install
```
## Basic Usage
```Python
from ouroboros.dev import *
```
Server side: Accepting a flow:
```Python
f = flow_accept()
```
returns a new allocated flow object.
Client side: Allocating a flow to a certain _name_:
```Python
f = flow_alloc("name")
```
returns a new allocated Flow object.
Broadcast:
```Python
f = flow_join("name")
```
returns a new allocated Flow object.
Deallocation:
```Python
f.dealloc()
```
To avoid having to call dealloc(), you can use the with statement:
```Python
with flow_alloc("dst") as f:
f.writeline("line")
print(f.readline())
```
deallocates the flow. After this call, the Flow object is not readable
or writeable anymore.
```Python
f.alloc("name")
```
will allocate a new flow for an existing Flow object.
To read / write from a flow:
```Python
f.read(count) # read up to _count_ bytes and return bytes
f.readline(count) # read up to _count_ characters as a string
f.write(buf, count) # write up to _count_ bytes from buffer
f.writeline(str, count) # write up to _count_ characters from string
```
## Quality of Service (QoS)
The QoS spec details have not been finalized in Ouroboros. It is just
here to give a general idea and to control some basics of the flow.
You can specify a QoSSpec for flow allocation.
For instance,
```Python
qos = QoSSpec(loss=0, cypher_s=256, timeout=60000)
f = flow_alloc("name", qos)
```
will create a new flow with FRCP retransmission enabled and encrypted
using a 256-bit ECDHE-AES-SHA3 cypher that will timeout if the peer is
not responsive for 1 minute.
## Manipulating flows
A number of methods are available for how to interact with Flow
```Python
f.set_snd_timeout(0.5) # set timeout for blocking write
f.set_rcv_timeout(1.0) # set timeout for blocking read
f.get_snd_timeout() # get timeout for blocking write
f.get_rcv_timeout() # get timeout for blocking read
f.get_qos() # get the QoSSpec for this flow
f.get_rx_queue_len() # get the number of packets in the rx buffer
f.get_tx_queue_len() # get the number of packets in the tx buffer
f.set_flags(flags) # set a number of flags for this flow
f.get_flags() # get the flags for this flow
```
The flags are specified as an enum FlowProperties:
```Python
class FlowProperties(IntFlag):
ReadOnly
WriteOnly
ReadWrite
Down
NonBlockingRead
NonBlockingWrite
NonBlocking
NoPartialRead
NoPartialWrite
```
See the Ouroboros fccntl documentation for more details.
```shell
man fccntl
```
## Event API
Multiple flows can be monitored for activity in parallel using a
FlowSet and FEventQueue objects.
FlowSets allow grouping a bunch of Flow objects together to listen for
activity. It can be constructed with an optional list of Flows, or
flows can be added or removed using the following methods:
```Python
set = FlowSet() # create a flow set,
set.add(f) # add a Flow 'f' to this set
set.remove(f) # remove a Flow 'f' from this set
set.zero() # remove all Flows in this set
```
An FEventQueue stores pending events on flows.
The event types are defined as follows:
```Python
class FEventType(IntFlag):
FlowPkt
FlowDown
FlowUp
FlowAlloc
FlowDealloc
```
and can be obtained by calling the next method:
```Python
f, t = fq.next() # Return active flow 'f' and type of event 't'
```
An FEventQueue is populated from a FlowSet.
```Python
fq = FEventQueue() # Create an eventqueue
set = FlowSet([f1, f2, f3]) # Create a new set with a couple of Flow objects
set.wait(fq, timeo=1.0) # Wait for 1 second or until event
while f, t = fq.next():
if t == FEventType.FlowPkt:
msg = f.readline()
...
set.destroy()
```
A flow_set must be destroyed when it goes out of scope.
To avoid having to call destroy, Python's with statement can be used:
```Python
fq = FEventQueue()
with FlowSet([f]) as fs:
fs.wait(fq)
f2, t = fq.next()
if t == FEventType.FlowPkt:
line = f2.readline()
```
## Examples
Some example code is in the examples folder.
## License
pyOuorboros is LGPLv2.1. The examples are 3-clause BSD.
|
