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/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