readwebform 0.4.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- readwebform/__init__.py +63 -0
- readwebform/__main__.py +10 -0
- readwebform/api.py +335 -0
- readwebform/browser.py +115 -0
- readwebform/cli.py +267 -0
- readwebform/core.py +241 -0
- readwebform/forms.py +408 -0
- readwebform/multipart.py +399 -0
- readwebform/output.py +171 -0
- readwebform/parser.py +285 -0
- readwebform/py.typed +0 -0
- readwebform/server.py +690 -0
- readwebform-0.4.0.dist-info/METADATA +710 -0
- readwebform-0.4.0.dist-info/RECORD +18 -0
- readwebform-0.4.0.dist-info/WHEEL +5 -0
- readwebform-0.4.0.dist-info/entry_points.txt +2 -0
- readwebform-0.4.0.dist-info/licenses/LICENSE +21 -0
- readwebform-0.4.0.dist-info/top_level.txt +1 -0
readwebform/server.py
ADDED
|
@@ -0,0 +1,690 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Ephemeral web server for readwebform.
|
|
3
|
+
|
|
4
|
+
Lifecycle
|
|
5
|
+
---------
|
|
6
|
+
``FormServer.serve()`` binds a listening socket, runs a threaded HTTP server
|
|
7
|
+
in a background thread, starts a timeout timer, and waits. The first of these
|
|
8
|
+
events wins and is recorded as the session's outcome under a lock:
|
|
9
|
+
|
|
10
|
+
* a valid submission (``success``)
|
|
11
|
+
* a cancel-button submission (``cancelled``)
|
|
12
|
+
* the timeout timer firing (``timeout``)
|
|
13
|
+
* ``shutdown_event`` being set from outside (``stopped``)
|
|
14
|
+
|
|
15
|
+
Once an outcome is recorded nothing else can change it. A submission that
|
|
16
|
+
loses the race receives HTTP 410 and any files it saved are removed. After
|
|
17
|
+
the winning handler has finished writing its response it releases the main
|
|
18
|
+
thread, which shuts the server down, closes the listener and any lingering
|
|
19
|
+
connections, and returns.
|
|
20
|
+
|
|
21
|
+
Each connection is handled on its own thread with a socket timeout, so an
|
|
22
|
+
idle keep-alive connection or a half-sent request can never block the accept
|
|
23
|
+
loop. For HTTPS the TLS handshake is performed on the connection thread for
|
|
24
|
+
the same reason.
|
|
25
|
+
"""
|
|
26
|
+
|
|
27
|
+
import html
|
|
28
|
+
import http.server
|
|
29
|
+
import os
|
|
30
|
+
import secrets
|
|
31
|
+
import socket
|
|
32
|
+
import socketserver
|
|
33
|
+
import ssl
|
|
34
|
+
import sys
|
|
35
|
+
import tempfile
|
|
36
|
+
import threading
|
|
37
|
+
from typing import Optional, cast
|
|
38
|
+
|
|
39
|
+
from .browser import launch_browser
|
|
40
|
+
from .multipart import (
|
|
41
|
+
FormData,
|
|
42
|
+
FormParseError,
|
|
43
|
+
SizeLimitExceeded,
|
|
44
|
+
parse_multipart,
|
|
45
|
+
parse_urlencoded,
|
|
46
|
+
save_uploaded_file,
|
|
47
|
+
)
|
|
48
|
+
|
|
49
|
+
# Maximum request body size when no limit is configured (prevents memory exhaustion)
|
|
50
|
+
DEFAULT_MAX_BODY_SIZE = 20 * 1024 * 1024 # 20 MB
|
|
51
|
+
|
|
52
|
+
# Idle timeout for an accepted connection (seconds). Bounds how long a client
|
|
53
|
+
# that has connected but not finished sending a request can hold a thread.
|
|
54
|
+
CONNECTION_TIMEOUT = 30.0
|
|
55
|
+
|
|
56
|
+
OUTCOME_SUCCESS = 'success'
|
|
57
|
+
OUTCOME_CANCELLED = 'cancelled'
|
|
58
|
+
OUTCOME_TIMEOUT = 'timeout'
|
|
59
|
+
OUTCOME_STOPPED = 'stopped'
|
|
60
|
+
|
|
61
|
+
_QUIET_ERRORS = (ssl.SSLError, socket.timeout, TimeoutError, ConnectionError)
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
class SessionFinished(RuntimeError):
|
|
65
|
+
"""Raised when a handler tries to do work after the session's outcome is set."""
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
class _FormHTTPServer(http.server.ThreadingHTTPServer):
|
|
69
|
+
"""Threaded HTTP server that carries the owning FormServer as instance state."""
|
|
70
|
+
|
|
71
|
+
daemon_threads = True
|
|
72
|
+
allow_reuse_address = True
|
|
73
|
+
|
|
74
|
+
def __init__(self, address: tuple[str, int], session: 'FormServer',
|
|
75
|
+
ssl_context: Optional[ssl.SSLContext]):
|
|
76
|
+
self.session = session
|
|
77
|
+
self.ssl_context = ssl_context
|
|
78
|
+
self.address_family = socket.AF_INET6 if ':' in address[0] else socket.AF_INET
|
|
79
|
+
self._connections: set[socket.socket] = set()
|
|
80
|
+
self._connections_lock = threading.Lock()
|
|
81
|
+
super().__init__(address, FormServerHandler)
|
|
82
|
+
|
|
83
|
+
def server_bind(self):
|
|
84
|
+
# HTTPServer.server_bind() calls socket.getfqdn(), which can stall for
|
|
85
|
+
# seconds on hosts with slow reverse DNS. We never use server_name.
|
|
86
|
+
socketserver.TCPServer.server_bind(self)
|
|
87
|
+
self.server_name = str(self.server_address[0])
|
|
88
|
+
self.server_port = int(self.server_address[1])
|
|
89
|
+
|
|
90
|
+
def track_connection(self, conn: socket.socket) -> None:
|
|
91
|
+
with self._connections_lock:
|
|
92
|
+
self._connections.add(conn)
|
|
93
|
+
|
|
94
|
+
def untrack_connection(self, conn: socket.socket) -> None:
|
|
95
|
+
with self._connections_lock:
|
|
96
|
+
self._connections.discard(conn)
|
|
97
|
+
|
|
98
|
+
def server_close(self):
|
|
99
|
+
super().server_close()
|
|
100
|
+
# Close connections whose handlers are still blocked reading, so a
|
|
101
|
+
# browser's idle keep-alive socket does not outlive the session.
|
|
102
|
+
with self._connections_lock:
|
|
103
|
+
conns = list(self._connections)
|
|
104
|
+
self._connections.clear()
|
|
105
|
+
for conn in conns:
|
|
106
|
+
try:
|
|
107
|
+
conn.shutdown(socket.SHUT_RDWR)
|
|
108
|
+
except OSError:
|
|
109
|
+
pass
|
|
110
|
+
try:
|
|
111
|
+
conn.close()
|
|
112
|
+
except OSError:
|
|
113
|
+
pass
|
|
114
|
+
|
|
115
|
+
def handle_error(self, request, client_address):
|
|
116
|
+
exc = sys.exc_info()[1]
|
|
117
|
+
if isinstance(exc, _QUIET_ERRORS):
|
|
118
|
+
# Idle connections timing out, TLS probes, clients going away:
|
|
119
|
+
# routine, not worth a traceback.
|
|
120
|
+
return
|
|
121
|
+
print(f'readwebform: error handling request from {client_address[0]}: {exc!r}',
|
|
122
|
+
file=sys.stderr)
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
class FormServerHandler(http.server.BaseHTTPRequestHandler):
|
|
126
|
+
"""HTTP request handler for form serving and submission."""
|
|
127
|
+
|
|
128
|
+
timeout = CONNECTION_TIMEOUT
|
|
129
|
+
server_version = 'readwebform'
|
|
130
|
+
sys_version = ''
|
|
131
|
+
|
|
132
|
+
@property
|
|
133
|
+
def form_server(self) -> _FormHTTPServer:
|
|
134
|
+
return cast(_FormHTTPServer, self.server)
|
|
135
|
+
|
|
136
|
+
@property
|
|
137
|
+
def session(self) -> 'FormServer':
|
|
138
|
+
return self.form_server.session
|
|
139
|
+
|
|
140
|
+
def setup(self):
|
|
141
|
+
ctx = self.form_server.ssl_context
|
|
142
|
+
if ctx is not None:
|
|
143
|
+
# Handshake here, on the connection thread and under the socket
|
|
144
|
+
# timeout, rather than inside accept() on the serving thread.
|
|
145
|
+
# wrap_socket() moves the descriptor to a new SSLSocket, so track
|
|
146
|
+
# that object: it is the one server_close() must close.
|
|
147
|
+
self.request.settimeout(self.timeout)
|
|
148
|
+
self.request = ctx.wrap_socket(self.request, server_side=True,
|
|
149
|
+
do_handshake_on_connect=False)
|
|
150
|
+
self.form_server.track_connection(self.request)
|
|
151
|
+
try:
|
|
152
|
+
self.request.do_handshake()
|
|
153
|
+
except BaseException:
|
|
154
|
+
self.form_server.untrack_connection(self.request)
|
|
155
|
+
self.request.close()
|
|
156
|
+
raise
|
|
157
|
+
else:
|
|
158
|
+
self.form_server.track_connection(self.request)
|
|
159
|
+
super().setup()
|
|
160
|
+
|
|
161
|
+
def finish(self):
|
|
162
|
+
try:
|
|
163
|
+
super().finish()
|
|
164
|
+
finally:
|
|
165
|
+
self.form_server.untrack_connection(self.request)
|
|
166
|
+
if self.form_server.ssl_context is not None:
|
|
167
|
+
try:
|
|
168
|
+
self.request.close()
|
|
169
|
+
except OSError:
|
|
170
|
+
pass
|
|
171
|
+
|
|
172
|
+
def log_message(self, format, *args):
|
|
173
|
+
"""Suppress default request logging."""
|
|
174
|
+
|
|
175
|
+
def do_GET(self):
|
|
176
|
+
"""Serve the form."""
|
|
177
|
+
if self.path.split('?', 1)[0] != self.session.endpoint:
|
|
178
|
+
self.send_error(404, 'Not Found')
|
|
179
|
+
return
|
|
180
|
+
|
|
181
|
+
body = self.session.html.encode('utf-8')
|
|
182
|
+
self.send_response(200)
|
|
183
|
+
self.send_header('Content-Type', 'text/html; charset=utf-8')
|
|
184
|
+
self.send_header('Content-Length', str(len(body)))
|
|
185
|
+
self.send_header('Cache-Control', 'no-store, no-cache, must-revalidate')
|
|
186
|
+
self.send_header('X-Content-Type-Options', 'nosniff')
|
|
187
|
+
self.end_headers()
|
|
188
|
+
self.wfile.write(body)
|
|
189
|
+
|
|
190
|
+
def do_POST(self):
|
|
191
|
+
"""Process a form submission."""
|
|
192
|
+
session = self.session
|
|
193
|
+
|
|
194
|
+
if self.path.split('?', 1)[0] != session.endpoint:
|
|
195
|
+
self.send_error(404, 'Not Found')
|
|
196
|
+
return
|
|
197
|
+
|
|
198
|
+
if session.is_finished():
|
|
199
|
+
self._send_error_page(410, 'Gone', 'This form has already been completed')
|
|
200
|
+
return
|
|
201
|
+
|
|
202
|
+
content_type = self.headers.get('Content-Type', '')
|
|
203
|
+
length_header = self.headers.get('Content-Length')
|
|
204
|
+
if length_header is None:
|
|
205
|
+
self._send_error_page(411, 'Length Required', 'Content-Length header is required')
|
|
206
|
+
return
|
|
207
|
+
try:
|
|
208
|
+
content_length = int(length_header)
|
|
209
|
+
if content_length < 0:
|
|
210
|
+
raise ValueError('negative')
|
|
211
|
+
except ValueError:
|
|
212
|
+
self._send_error_page(400, 'Bad Request', 'Invalid Content-Length header')
|
|
213
|
+
return
|
|
214
|
+
|
|
215
|
+
effective_max = session.max_total_size
|
|
216
|
+
if effective_max is None:
|
|
217
|
+
effective_max = DEFAULT_MAX_BODY_SIZE
|
|
218
|
+
|
|
219
|
+
if content_length > effective_max:
|
|
220
|
+
self._send_error_page(
|
|
221
|
+
413, 'Payload Too Large',
|
|
222
|
+
f'Total upload size ({content_length} bytes) exceeds limit ({effective_max} bytes)'
|
|
223
|
+
)
|
|
224
|
+
session.note_recoverable_error()
|
|
225
|
+
return
|
|
226
|
+
|
|
227
|
+
try:
|
|
228
|
+
body = self.rfile.read(content_length)
|
|
229
|
+
except OSError as e:
|
|
230
|
+
self._send_error_page(400, 'Bad Request', f'Failed to read request body: {e}')
|
|
231
|
+
return
|
|
232
|
+
if len(body) != content_length:
|
|
233
|
+
self._send_error_page(400, 'Bad Request', 'Request body shorter than Content-Length')
|
|
234
|
+
return
|
|
235
|
+
|
|
236
|
+
try:
|
|
237
|
+
if 'multipart/form-data' in content_type:
|
|
238
|
+
form_data = parse_multipart(body, content_type,
|
|
239
|
+
session.max_file_size, session.max_total_size)
|
|
240
|
+
else:
|
|
241
|
+
form_data = parse_urlencoded(body)
|
|
242
|
+
except SizeLimitExceeded as e:
|
|
243
|
+
self._send_error_page(413, 'Payload Too Large', str(e))
|
|
244
|
+
session.note_recoverable_error()
|
|
245
|
+
print(f'Upload limit exceeded: {e}', file=sys.stderr)
|
|
246
|
+
return
|
|
247
|
+
except (FormParseError, Exception) as e:
|
|
248
|
+
self._send_error_page(400, 'Bad Request', f'Failed to parse form data: {e}')
|
|
249
|
+
session.note_recoverable_error()
|
|
250
|
+
return
|
|
251
|
+
|
|
252
|
+
submitted_token = form_data.fields.pop('_csrf_token', '')
|
|
253
|
+
if isinstance(submitted_token, list) or not secrets.compare_digest(
|
|
254
|
+
str(submitted_token).encode('utf-8'), session.csrf_token.encode('utf-8')):
|
|
255
|
+
self._send_error_page(403, 'Forbidden', 'Invalid CSRF token')
|
|
256
|
+
session.note_recoverable_error()
|
|
257
|
+
return
|
|
258
|
+
|
|
259
|
+
if '_cancel' in form_data.fields:
|
|
260
|
+
form_data.fields.pop('_cancel', None)
|
|
261
|
+
if not session.complete(OUTCOME_CANCELLED):
|
|
262
|
+
self._send_error_page(410, 'Gone', 'This form has already been completed')
|
|
263
|
+
return
|
|
264
|
+
try:
|
|
265
|
+
self._send_cancelled_page()
|
|
266
|
+
finally:
|
|
267
|
+
session.release()
|
|
268
|
+
return
|
|
269
|
+
|
|
270
|
+
file_metadata: dict = {}
|
|
271
|
+
saved_paths = []
|
|
272
|
+
try:
|
|
273
|
+
for name, uploaded_file in form_data.iter_files():
|
|
274
|
+
filepath = save_uploaded_file(uploaded_file, session.get_upload_dir())
|
|
275
|
+
saved_paths.append(filepath)
|
|
276
|
+
meta = {
|
|
277
|
+
'filename': uploaded_file.filename,
|
|
278
|
+
'path': filepath,
|
|
279
|
+
'size': uploaded_file.size,
|
|
280
|
+
'content_type': uploaded_file.content_type
|
|
281
|
+
}
|
|
282
|
+
if isinstance(form_data.files[name], list):
|
|
283
|
+
file_metadata.setdefault(name, []).append(meta)
|
|
284
|
+
else:
|
|
285
|
+
file_metadata[name] = meta
|
|
286
|
+
except SessionFinished:
|
|
287
|
+
_unlink_all(saved_paths)
|
|
288
|
+
session._cleanup_upload_dir()
|
|
289
|
+
self._send_error_page(410, 'Gone', 'This form has already been completed')
|
|
290
|
+
return
|
|
291
|
+
except Exception as e:
|
|
292
|
+
_unlink_all(saved_paths)
|
|
293
|
+
self._send_error_page(500, 'Internal Server Error', f'Failed to save file: {e}')
|
|
294
|
+
session.note_recoverable_error()
|
|
295
|
+
return
|
|
296
|
+
|
|
297
|
+
# Commit the result before responding so a client that disconnects
|
|
298
|
+
# mid-response cannot lose an accepted submission.
|
|
299
|
+
if not session.complete(OUTCOME_SUCCESS, form_data, file_metadata):
|
|
300
|
+
_unlink_all(saved_paths)
|
|
301
|
+
session._cleanup_upload_dir()
|
|
302
|
+
self._send_error_page(410, 'Gone', 'This form has already been completed')
|
|
303
|
+
return
|
|
304
|
+
|
|
305
|
+
try:
|
|
306
|
+
self._send_success_page()
|
|
307
|
+
finally:
|
|
308
|
+
session.release()
|
|
309
|
+
|
|
310
|
+
def _send_html(self, code: int, page: str):
|
|
311
|
+
body = page.encode('utf-8')
|
|
312
|
+
self.send_response(code)
|
|
313
|
+
self.send_header('Content-Type', 'text/html; charset=utf-8')
|
|
314
|
+
self.send_header('Content-Length', str(len(body)))
|
|
315
|
+
self.send_header('Cache-Control', 'no-store')
|
|
316
|
+
self.end_headers()
|
|
317
|
+
self.wfile.write(body)
|
|
318
|
+
|
|
319
|
+
def _send_success_page(self):
|
|
320
|
+
self._send_html(200, _status_page('Success', 'success', '✅ Form submitted successfully',
|
|
321
|
+
'You may now close this window.'))
|
|
322
|
+
|
|
323
|
+
def _send_cancelled_page(self):
|
|
324
|
+
self._send_html(200, _status_page('Cancelled', 'cancelled', 'Form submission cancelled',
|
|
325
|
+
'You may now close this window.'))
|
|
326
|
+
|
|
327
|
+
def _send_error_page(self, code: int, title: str, message: str):
|
|
328
|
+
back = f'<div class="back"><a href="{html.escape(self.session.endpoint)}">← Go back</a></div>'
|
|
329
|
+
self._send_html(code, _status_page(title, 'error', '❌ ' + title, message, back))
|
|
330
|
+
|
|
331
|
+
|
|
332
|
+
def _primary_address(ipv6: bool = False) -> Optional[str]:
|
|
333
|
+
"""
|
|
334
|
+
Best-effort address of the interface that carries default-route traffic.
|
|
335
|
+
|
|
336
|
+
Connecting a UDP socket sends nothing; it only asks the kernel which local
|
|
337
|
+
address it would use for the target. The targets are documentation
|
|
338
|
+
addresses (TEST-NET-1 and 2001:db8::/32) so the lookup follows the default
|
|
339
|
+
route rather than a private-range route such as a VPN's 10/8. Returns None
|
|
340
|
+
when no route exists. The answer is a guess: a full-tunnel VPN still wins.
|
|
341
|
+
"""
|
|
342
|
+
family = socket.AF_INET6 if ipv6 else socket.AF_INET
|
|
343
|
+
target = ('2001:db8::1', 9) if ipv6 else ('192.0.2.1', 9)
|
|
344
|
+
try:
|
|
345
|
+
with socket.socket(family, socket.SOCK_DGRAM) as probe:
|
|
346
|
+
probe.connect(target)
|
|
347
|
+
address = probe.getsockname()[0]
|
|
348
|
+
except OSError:
|
|
349
|
+
return None
|
|
350
|
+
if address in ('0.0.0.0', '::'):
|
|
351
|
+
return None
|
|
352
|
+
return address
|
|
353
|
+
|
|
354
|
+
|
|
355
|
+
def _unlink_all(paths):
|
|
356
|
+
for path in paths:
|
|
357
|
+
try:
|
|
358
|
+
os.unlink(path)
|
|
359
|
+
except OSError:
|
|
360
|
+
pass
|
|
361
|
+
|
|
362
|
+
|
|
363
|
+
def _status_page(title: str, css_class: str, heading: str, message: str, extra: str = '') -> str:
|
|
364
|
+
"""Render a minimal status page. All text arguments are escaped."""
|
|
365
|
+
return f'''<!DOCTYPE html>
|
|
366
|
+
<html>
|
|
367
|
+
<head>
|
|
368
|
+
<meta charset="UTF-8">
|
|
369
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
370
|
+
<title>{html.escape(title)}</title>
|
|
371
|
+
<style>
|
|
372
|
+
body {{
|
|
373
|
+
font-family: system-ui, -apple-system, sans-serif;
|
|
374
|
+
max-width: 600px;
|
|
375
|
+
margin: 100px auto;
|
|
376
|
+
padding: 20px;
|
|
377
|
+
text-align: center;
|
|
378
|
+
}}
|
|
379
|
+
.status {{ font-size: 24px; font-weight: 500; }}
|
|
380
|
+
.success {{ color: #28a745; }}
|
|
381
|
+
.cancelled {{ color: #6c757d; }}
|
|
382
|
+
.error {{ color: #dc3545; }}
|
|
383
|
+
.back {{ margin-top: 20px; }}
|
|
384
|
+
a {{ color: #007bff; text-decoration: none; }}
|
|
385
|
+
</style>
|
|
386
|
+
</head>
|
|
387
|
+
<body>
|
|
388
|
+
<div class="status {css_class}">{html.escape(heading)}</div>
|
|
389
|
+
<p>{html.escape(message)}</p>
|
|
390
|
+
{extra}
|
|
391
|
+
</body>
|
|
392
|
+
</html>'''
|
|
393
|
+
|
|
394
|
+
|
|
395
|
+
class FormServer:
|
|
396
|
+
"""Ephemeral form server with CSRF protection and timeout management."""
|
|
397
|
+
|
|
398
|
+
def __init__(
|
|
399
|
+
self,
|
|
400
|
+
html: str,
|
|
401
|
+
host: str = '127.0.0.1',
|
|
402
|
+
port: Optional[int] = None,
|
|
403
|
+
max_file_size: Optional[int] = None,
|
|
404
|
+
max_total_size: Optional[int] = None,
|
|
405
|
+
timeout: float = 300,
|
|
406
|
+
reset_timeout_on_error: bool = True,
|
|
407
|
+
cert_file: Optional[str] = None,
|
|
408
|
+
key_file: Optional[str] = None,
|
|
409
|
+
upload_dir: Optional[str] = None,
|
|
410
|
+
url_host: Optional[str] = None
|
|
411
|
+
):
|
|
412
|
+
"""
|
|
413
|
+
Initialize form server.
|
|
414
|
+
|
|
415
|
+
Args:
|
|
416
|
+
html: HTML content to serve (may be replaced via ``.html`` before serve())
|
|
417
|
+
host: Host to bind to (IPv4 or IPv6 address)
|
|
418
|
+
port: Port to bind to (None = auto-select)
|
|
419
|
+
max_file_size: Maximum individual file size in bytes (None = no limit)
|
|
420
|
+
max_total_size: Maximum total upload size in bytes (None = default cap)
|
|
421
|
+
timeout: Seconds to wait for a submission
|
|
422
|
+
reset_timeout_on_error: Restart the timeout after a recoverable error
|
|
423
|
+
cert_file: Path to SSL certificate file (PEM format)
|
|
424
|
+
key_file: Path to SSL private key file (PEM format)
|
|
425
|
+
upload_dir: Directory for uploaded files (None = a temporary
|
|
426
|
+
directory created on first upload and removed if left empty)
|
|
427
|
+
url_host: Host to put in the printed URL. Defaults to the bind
|
|
428
|
+
host, or for a wildcard bind to a best-effort guess of this
|
|
429
|
+
machine's outbound address.
|
|
430
|
+
"""
|
|
431
|
+
self.html = html
|
|
432
|
+
self.host = host
|
|
433
|
+
self.port = port or 0 # 0 = auto-select free port
|
|
434
|
+
self.max_file_size = max_file_size
|
|
435
|
+
self.max_total_size = max_total_size
|
|
436
|
+
self.timeout = timeout
|
|
437
|
+
self.reset_timeout_on_error = reset_timeout_on_error
|
|
438
|
+
if (cert_file is None) != (key_file is None):
|
|
439
|
+
raise ValueError('cert_file and key_file must be given together')
|
|
440
|
+
self.cert_file = cert_file
|
|
441
|
+
self.key_file = key_file
|
|
442
|
+
self.use_ssl = cert_file is not None and key_file is not None
|
|
443
|
+
|
|
444
|
+
self.csrf_token = secrets.token_hex(16)
|
|
445
|
+
self.endpoint = '/readform_' + secrets.token_hex(8)
|
|
446
|
+
|
|
447
|
+
self.upload_dir: Optional[str] = upload_dir
|
|
448
|
+
self._created_upload_dir = False
|
|
449
|
+
self.url_host = url_host
|
|
450
|
+
|
|
451
|
+
# Outcome state, guarded by _lock
|
|
452
|
+
self._lock = threading.Lock()
|
|
453
|
+
self._outcome: Optional[str] = None
|
|
454
|
+
self.form_data: Optional[FormData] = None
|
|
455
|
+
self.file_metadata: dict = {}
|
|
456
|
+
self.timeout_timer: Optional[threading.Timer] = None
|
|
457
|
+
self._timer_generation = 0
|
|
458
|
+
|
|
459
|
+
# Set when serve() should stop waiting. Setting it from outside stops
|
|
460
|
+
# the server (outcome 'stopped').
|
|
461
|
+
self.shutdown_event = threading.Event()
|
|
462
|
+
|
|
463
|
+
self.server: Optional[_FormHTTPServer] = None
|
|
464
|
+
self._url = ''
|
|
465
|
+
|
|
466
|
+
# -- outcome ---------------------------------------------------------
|
|
467
|
+
|
|
468
|
+
@property
|
|
469
|
+
def outcome(self) -> Optional[str]:
|
|
470
|
+
return self._outcome
|
|
471
|
+
|
|
472
|
+
@property
|
|
473
|
+
def success(self) -> bool:
|
|
474
|
+
return self._outcome == OUTCOME_SUCCESS
|
|
475
|
+
|
|
476
|
+
@property
|
|
477
|
+
def cancelled(self) -> bool:
|
|
478
|
+
return self._outcome == OUTCOME_CANCELLED
|
|
479
|
+
|
|
480
|
+
@property
|
|
481
|
+
def timed_out(self) -> bool:
|
|
482
|
+
return self._outcome == OUTCOME_TIMEOUT
|
|
483
|
+
|
|
484
|
+
def is_finished(self) -> bool:
|
|
485
|
+
return self._outcome is not None or self.shutdown_event.is_set()
|
|
486
|
+
|
|
487
|
+
def complete(self, outcome: str, form_data: Optional[FormData] = None,
|
|
488
|
+
file_metadata: Optional[dict] = None) -> bool:
|
|
489
|
+
"""
|
|
490
|
+
Record the session outcome. Only the first call succeeds.
|
|
491
|
+
|
|
492
|
+
Returns:
|
|
493
|
+
True if this call recorded the outcome, False if one was already set.
|
|
494
|
+
"""
|
|
495
|
+
with self._lock:
|
|
496
|
+
return self._complete_locked(outcome, form_data, file_metadata)
|
|
497
|
+
|
|
498
|
+
def _complete_locked(self, outcome: str, form_data: Optional[FormData],
|
|
499
|
+
file_metadata: Optional[dict]) -> bool:
|
|
500
|
+
if self._outcome is not None or self.shutdown_event.is_set():
|
|
501
|
+
return False
|
|
502
|
+
self._outcome = outcome
|
|
503
|
+
self.form_data = form_data
|
|
504
|
+
self.file_metadata = file_metadata or {}
|
|
505
|
+
if self.timeout_timer is not None:
|
|
506
|
+
self.timeout_timer.cancel()
|
|
507
|
+
self.timeout_timer = None
|
|
508
|
+
return True
|
|
509
|
+
|
|
510
|
+
def release(self) -> None:
|
|
511
|
+
"""Let serve() return. Called after the final response has been written."""
|
|
512
|
+
self.shutdown_event.set()
|
|
513
|
+
|
|
514
|
+
# -- timeout ---------------------------------------------------------
|
|
515
|
+
|
|
516
|
+
def _start_timer(self) -> None:
|
|
517
|
+
with self._lock:
|
|
518
|
+
if self.timeout_timer is not None:
|
|
519
|
+
self.timeout_timer.cancel()
|
|
520
|
+
self.timeout_timer = None
|
|
521
|
+
if self._outcome is not None:
|
|
522
|
+
return
|
|
523
|
+
# Timer.cancel() cannot stop a callback that has already started
|
|
524
|
+
# and is waiting for the lock, so each timer carries a generation
|
|
525
|
+
# and a stale callback is ignored.
|
|
526
|
+
self._timer_generation += 1
|
|
527
|
+
self.timeout_timer = threading.Timer(self.timeout, self._on_timeout,
|
|
528
|
+
args=(self._timer_generation,))
|
|
529
|
+
self.timeout_timer.daemon = True
|
|
530
|
+
self.timeout_timer.start()
|
|
531
|
+
|
|
532
|
+
def reset_timeout(self) -> None:
|
|
533
|
+
"""Restart the timeout timer (used after recoverable errors)."""
|
|
534
|
+
if self.reset_timeout_on_error:
|
|
535
|
+
self._start_timer()
|
|
536
|
+
|
|
537
|
+
def note_recoverable_error(self) -> None:
|
|
538
|
+
self.reset_timeout()
|
|
539
|
+
|
|
540
|
+
def _on_timeout(self, generation: Optional[int] = None) -> None:
|
|
541
|
+
with self._lock:
|
|
542
|
+
if generation is not None and generation != self._timer_generation:
|
|
543
|
+
return # a reset replaced this timer while its callback was pending
|
|
544
|
+
completed = self._complete_locked(OUTCOME_TIMEOUT, None, None)
|
|
545
|
+
if completed:
|
|
546
|
+
self.release()
|
|
547
|
+
|
|
548
|
+
# -- uploads ---------------------------------------------------------
|
|
549
|
+
|
|
550
|
+
def get_upload_dir(self) -> str:
|
|
551
|
+
"""Return the upload directory, creating a temporary one on first use."""
|
|
552
|
+
with self._lock:
|
|
553
|
+
if self._outcome is not None or self.shutdown_event.is_set():
|
|
554
|
+
raise SessionFinished('session already completed')
|
|
555
|
+
if self.upload_dir is None:
|
|
556
|
+
self.upload_dir = tempfile.mkdtemp(prefix='readwebform_')
|
|
557
|
+
self._created_upload_dir = True
|
|
558
|
+
elif not os.path.isdir(self.upload_dir):
|
|
559
|
+
os.makedirs(self.upload_dir, mode=0o700, exist_ok=True)
|
|
560
|
+
return self.upload_dir
|
|
561
|
+
|
|
562
|
+
def _cleanup_upload_dir(self) -> None:
|
|
563
|
+
if self._created_upload_dir and self.upload_dir:
|
|
564
|
+
try:
|
|
565
|
+
os.rmdir(self.upload_dir) # only succeeds if empty
|
|
566
|
+
except OSError:
|
|
567
|
+
pass
|
|
568
|
+
|
|
569
|
+
# -- serving ---------------------------------------------------------
|
|
570
|
+
|
|
571
|
+
def _build_ssl_context(self) -> ssl.SSLContext:
|
|
572
|
+
assert self.cert_file is not None and self.key_file is not None
|
|
573
|
+
context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
|
|
574
|
+
try:
|
|
575
|
+
context.load_cert_chain(certfile=self.cert_file, keyfile=self.key_file)
|
|
576
|
+
except ssl.SSLError as e:
|
|
577
|
+
print(f'Error: SSL configuration failed: {e}', file=sys.stderr)
|
|
578
|
+
raise
|
|
579
|
+
except FileNotFoundError as e:
|
|
580
|
+
print(f'Error: SSL certificate or key file not found: {e}', file=sys.stderr)
|
|
581
|
+
raise
|
|
582
|
+
return context
|
|
583
|
+
|
|
584
|
+
def is_wildcard_host(self) -> bool:
|
|
585
|
+
return self.host in ('', '0.0.0.0', '::')
|
|
586
|
+
|
|
587
|
+
def _display_host(self) -> str:
|
|
588
|
+
"""The host to put in the URL: an explicit url_host, the bind host, or a best-effort guess."""
|
|
589
|
+
if self.url_host:
|
|
590
|
+
return self.url_host
|
|
591
|
+
if not self.is_wildcard_host():
|
|
592
|
+
return self.host
|
|
593
|
+
address = _primary_address(ipv6=(self.host == '::'))
|
|
594
|
+
if address:
|
|
595
|
+
return address
|
|
596
|
+
return socket.gethostname()
|
|
597
|
+
|
|
598
|
+
def _build_url(self, port: int) -> str:
|
|
599
|
+
protocol = 'https' if self.use_ssl else 'http'
|
|
600
|
+
host = self._display_host()
|
|
601
|
+
url_host = f'[{host}]' if ':' in host else host
|
|
602
|
+
return f'{protocol}://{url_host}:{port}{self.endpoint}'
|
|
603
|
+
|
|
604
|
+
def serve(self, launch_browser_path: Optional[str] = None,
|
|
605
|
+
url_file: Optional[str] = None) -> tuple[bool, Optional[FormData], dict, bool]:
|
|
606
|
+
"""
|
|
607
|
+
Start the server and wait for a submission, cancellation, or timeout.
|
|
608
|
+
|
|
609
|
+
Args:
|
|
610
|
+
launch_browser_path: If not None, launch a browser once the server
|
|
611
|
+
is ready. Empty string means the system default browser.
|
|
612
|
+
url_file: If provided, write the form URL to this file.
|
|
613
|
+
|
|
614
|
+
Returns:
|
|
615
|
+
Tuple of (success, form_data, file_metadata, cancelled)
|
|
616
|
+
|
|
617
|
+
Raises:
|
|
618
|
+
OSError: If the port is already in use or binding fails
|
|
619
|
+
ssl.SSLError: If the SSL certificate or key is invalid
|
|
620
|
+
"""
|
|
621
|
+
ssl_context = self._build_ssl_context() if self.use_ssl else None
|
|
622
|
+
|
|
623
|
+
try:
|
|
624
|
+
self.server = _FormHTTPServer((self.host, self.port), self, ssl_context)
|
|
625
|
+
except OSError as e:
|
|
626
|
+
print(f'Error: Failed to bind to {self.host}:{self.port}: {e}', file=sys.stderr)
|
|
627
|
+
raise
|
|
628
|
+
|
|
629
|
+
self._url = self._build_url(self.server.server_address[1])
|
|
630
|
+
server_thread = threading.Thread(target=self._run_server, daemon=True)
|
|
631
|
+
started = False
|
|
632
|
+
|
|
633
|
+
try:
|
|
634
|
+
print(f'\nOpen this URL in your browser:\n {self._url}', file=sys.stderr)
|
|
635
|
+
if self.is_wildcard_host() and not self.url_host:
|
|
636
|
+
print(' (listening on all interfaces; the address above is this machine\'s '
|
|
637
|
+
'outbound address, a best-effort guess. If others cannot reach it, '
|
|
638
|
+
'pass --url-host with the right one.)', file=sys.stderr)
|
|
639
|
+
print(file=sys.stderr)
|
|
640
|
+
|
|
641
|
+
if url_file:
|
|
642
|
+
with open(url_file, 'w', encoding='utf-8') as f:
|
|
643
|
+
f.write(self._url + '\n')
|
|
644
|
+
|
|
645
|
+
# Serve before launching the browser: some launchers block until
|
|
646
|
+
# the page has loaded.
|
|
647
|
+
server_thread.start()
|
|
648
|
+
started = True
|
|
649
|
+
self._start_timer()
|
|
650
|
+
|
|
651
|
+
if launch_browser_path is not None:
|
|
652
|
+
print('Opening the form in your browser (use --no-launch-browser to suppress)',
|
|
653
|
+
file=sys.stderr)
|
|
654
|
+
if not launch_browser(self._url, launch_browser_path or None):
|
|
655
|
+
print('Could not open a browser; open the URL above manually.', file=sys.stderr)
|
|
656
|
+
|
|
657
|
+
# Poll rather than wait() so Ctrl+C is honoured on every platform
|
|
658
|
+
while not self.shutdown_event.wait(0.5):
|
|
659
|
+
pass
|
|
660
|
+
finally:
|
|
661
|
+
with self._lock:
|
|
662
|
+
if self.timeout_timer is not None:
|
|
663
|
+
self.timeout_timer.cancel()
|
|
664
|
+
self.timeout_timer = None
|
|
665
|
+
if self._outcome is None:
|
|
666
|
+
self._outcome = OUTCOME_STOPPED
|
|
667
|
+
self.shutdown_event.set()
|
|
668
|
+
if started:
|
|
669
|
+
self.server.shutdown()
|
|
670
|
+
self.server.server_close()
|
|
671
|
+
if started:
|
|
672
|
+
server_thread.join(timeout=2.0)
|
|
673
|
+
self._cleanup_upload_dir()
|
|
674
|
+
|
|
675
|
+
if self.success:
|
|
676
|
+
return True, self.form_data, self.file_metadata, False
|
|
677
|
+
return False, None, {}, self.cancelled
|
|
678
|
+
|
|
679
|
+
def _run_server(self) -> None:
|
|
680
|
+
server = self.server
|
|
681
|
+
assert server is not None
|
|
682
|
+
try:
|
|
683
|
+
server.serve_forever(poll_interval=0.25)
|
|
684
|
+
except OSError as e:
|
|
685
|
+
if not self.shutdown_event.is_set():
|
|
686
|
+
print(f'Server error: {e}', file=sys.stderr)
|
|
687
|
+
|
|
688
|
+
def get_url(self) -> str:
|
|
689
|
+
"""Return the form URL, or '' before the server has bound."""
|
|
690
|
+
return self._url
|