A Unix-style Python web framework: filesystem routing, flat files, messages and cron, with CGI's simplicity at modern speed.

0 downloads

Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-web.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-web.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-web.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

Dan Quellhorst Replace multipart parser with stdlib-only implementation eb957a2 9 months, 2 weeks ago History
router.py · 14.4 KB · 430 lines
1"""Filesystem-based routing - like CGI but async"""
2import importlib
3import importlib.util
4import urllib.parse
5from pathlib import Path
6from .settings import BASE_DIR
7from .responses import html, text
8from .templating import render
9from .static import serve_static
10from .request import Request
11
12
13def parse_query_string(query_string: str) -> dict:
14 """Parse URL query string into dict"""
15 if not query_string:
16 return {}
17 return dict(urllib.parse.parse_qsl(query_string))
18
19
20def parse_form_data(body: bytes, content_type: str) -> tuple[dict, dict]:
21 """
22 Parse form data from request body. No external dependencies.
23
24 Returns:
25 tuple: (form_fields, files) where form_fields is a dict of field names to values,
26 and files is a dict of field names to file info dicts with keys:
27 - filename: original filename
28 - content: file content as bytes
29 - content_type: MIME type if available
30 """
31 if not body:
32 return {}, {}
33
34 # Handle application/x-www-form-urlencoded
35 if "application/x-www-form-urlencoded" in content_type:
36 return dict(urllib.parse.parse_qsl(body.decode("utf-8"))), {}
37
38 # Handle multipart/form-data (stdlib only, no external deps)
39 if "multipart/form-data" in content_type:
40 return _parse_multipart(body, content_type)
41
42 return {}, {}
43
44
45def _parse_multipart(body: bytes, content_type: str) -> tuple[dict, dict]:
46 """Parse multipart/form-data using only the standard library."""
47 import re
48
49 fields = {}
50 files = {}
51
52 # Extract boundary from Content-Type header
53 boundary_match = re.search(r'boundary=([^\s;]+)', content_type)
54 if not boundary_match:
55 return {}, {}
56
57 boundary = boundary_match.group(1).strip('"').encode()
58 delimiter = b'--' + boundary
59
60 # Split body on boundary markers
61 parts = body.split(delimiter)
62
63 for part in parts:
64 # Skip empty parts, preamble, and the closing delimiter
65 if not part or part.strip() == b'' or part.strip() == b'--':
66 continue
67 if part.startswith(b'--'):
68 continue
69
70 # Strip leading \r\n from boundary split
71 if part.startswith(b'\r\n'):
72 part = part[2:]
73 # Strip trailing \r\n before next boundary
74 if part.endswith(b'\r\n'):
75 part = part[:-2]
76
77 # Split headers from body (separated by \r\n\r\n)
78 header_end = part.find(b'\r\n\r\n')
79 if header_end == -1:
80 continue
81
82 header_bytes = part[:header_end]
83 part_body = part[header_end + 4:]
84
85 # Parse part headers
86 part_headers = {}
87 for header_line in header_bytes.split(b'\r\n'):
88 if b':' in header_line:
89 key, value = header_line.split(b':', 1)
90 part_headers[key.strip().lower().decode()] = value.strip().decode()
91
92 content_disp = part_headers.get('content-disposition', '')
93
94 # Extract field name
95 name_match = re.search(r'name="([^"]+)"', content_disp)
96 if not name_match:
97 continue
98 name = name_match.group(1)
99
100 # Extract filename (present = file upload, absent = form field)
101 filename_match = re.search(r'filename="([^"]*)"', content_disp)
102
103 if filename_match:
104 filename = filename_match.group(1)
105 if filename: # Skip empty filename (no file selected)
106 files[name] = {
107 'filename': filename,
108 'content': part_body,
109 'content_type': part_headers.get('content-type', 'application/octet-stream'),
110 }
111 else:
112 # Regular form field
113 fields[name] = part_body.decode('utf-8', errors='replace')
114
115 return fields, files
116
117
118def parse_cookies(headers: list) -> dict:
119 """Parse cookies from request headers"""
120 cookies = {}
121 for name, value in headers:
122 if name.lower() == b"cookie":
123 cookie_str = value.decode("utf-8") if isinstance(value, bytes) else value
124 for cookie in cookie_str.split(";"):
125 cookie = cookie.strip()
126 if "=" in cookie:
127 key, val = cookie.split("=", 1)
128 cookies[key.strip()] = val.strip()
129 return cookies
130
131
132def route(scope: dict, body: bytes = b"") -> tuple[int, list, list]:
133 """
134 Route a request based on filesystem conventions.
135
136 Routing order:
137 1. API handlers: api/{path}.py or parent api handlers
138 2. Templates: templates/{path}.html
139 3. Static files: public/{path}
140 4. 404
141
142 API handlers can handle sub-paths:
143 - /user/123 → api/user.py gets request with path_parts=['user', '123']
144 """
145 method = scope["method"]
146 path = scope["path"]
147 query_string = scope.get("query_string", b"").decode("utf-8")
148 headers = scope.get("headers", [])
149
150 # Get content type for form parsing
151 content_type = ""
152 for name, value in headers:
153 if name.lower() == b"content-type":
154 content_type = value.decode("utf-8") if isinstance(value, bytes) else value
155 break
156
157 # Clean path
158 clean_path = path.strip("/")
159 path_parts = [p for p in clean_path.split("/") if p] if clean_path else []
160
161 # Parse form data and files
162 form_data, files = parse_form_data(body, content_type)
163
164 # Build request context
165 request = Request({
166 "method": method,
167 "path": path,
168 "path_parts": path_parts,
169 "query": parse_query_string(query_string),
170 "form": form_data,
171 "files": files,
172 "cookies": parse_cookies(headers),
173 "headers": headers,
174 "body": body,
175 "scope": scope,
176 })
177
178 # 1. Try API handlers (with hierarchical fallback)
179 api_result = try_api_handler(path_parts, request)
180 if api_result:
181 return api_result
182
183 # 2. Try templates (GET only)
184 if method == "GET":
185 template_result = try_template(path_parts)
186 if template_result:
187 return template_result
188
189 # 3. Try static files (GET only)
190 if method == "GET":
191 static_result = serve_static(clean_path)
192 if static_result[0] != 404:
193 return static_result
194
195 # 4. 404
196 return 404, [("content-type", "text/plain")], [b"Not Found"]
197
198
199def try_api_handler(path_parts: list[str], request: dict):
200 """
201 Try to find an API handler, checking from most specific to least specific.
202
203 For /user/123/edit:
204 1. Try api/user/123/edit.py (exact match)
205 2. Try api/user/123/[xxx].py (pattern match)
206 3. Try api/user/123.py (parent handler)
207 4. Try api/user/[id].py (pattern match)
208 5. Try api/user.py (parent handler)
209 6. Try api.py (root handler)
210
211 Pattern matching: [id], [slug], [name] extract the value and pass as kwarg
212 """
213 api_dir = BASE_DIR / "api"
214
215 if not path_parts:
216 # Root path: try api.py only
217 root_handler = BASE_DIR / "api.py"
218 if root_handler.exists():
219 return load_and_call_handler(root_handler, request)
220 return None
221
222 # Try increasingly general paths
223 for i in range(len(path_parts), 0, -1):
224 # Try exact match first
225 partial_path = "/".join(path_parts[:i])
226 handler_file = api_dir / f"{partial_path}.py"
227
228 # Try pattern match before exact match fallback
229 # For /tasks/123, when i=2, check api/tasks/[id].py before api/tasks.py
230 parent_parts = path_parts[:i-1]
231 current_segment = path_parts[i-1]
232
233 if parent_parts:
234 parent_dir = api_dir / "/".join(parent_parts)
235 else:
236 parent_dir = api_dir
237
238 if parent_dir.exists() and parent_dir.is_dir():
239 # Find pattern files like [id].py, [slug].py
240 # Must escape brackets in glob: [[]*.py matches literal [
241 for pattern_file in parent_dir.glob("[[]*.py"):
242 # Extract parameter name from [id].py -> id
243 param_name = pattern_file.stem.strip("[]")
244 param_value = current_segment
245
246 request["matched_parts"] = path_parts[:i]
247 request["remaining_parts"] = path_parts[i:]
248 request["path_params"] = {param_name: param_value}
249
250 return load_and_call_handler(pattern_file, request, **{param_name: param_value})
251
252 # Now try exact match as fallback
253 if handler_file.exists():
254 request["matched_parts"] = path_parts[:i]
255 request["remaining_parts"] = path_parts[i:]
256 return load_and_call_handler(handler_file, request)
257
258 # Try package handlers as fallback (e.g., dbbasic_admin.api.{path})
259 package_result = try_package_handler(path_parts, request)
260 if package_result:
261 return package_result
262
263 return None
264
265
266def try_package_handler(path_parts: list[str], request: dict):
267 """
268 Try to find a handler in installed packages.
269
270 For /admin/accounts/users, tries:
271 1. dbbasic_admin.api.accounts.users (admin-provided handler)
272 2. dbbasic_accounts.api.accounts.users (accounts package handler)
273
274 For /admin/database, tries:
275 1. dbbasic_admin.api.database (admin-provided handler)
276
277 This allows packages like dbbasic-admin to provide default handlers,
278 but also allows other packages to provide their own admin handlers.
279 """
280 if not path_parts:
281 return None
282
283 # For /admin/..., check dbbasic_admin package first
284 first_segment = path_parts[0]
285 package_name = f"dbbasic_{first_segment}"
286
287 try:
288 # Try to import the package
289 package = importlib.import_module(package_name)
290
291 # Build module path: dbbasic_admin.api.database
292 remaining_parts = path_parts[1:] if len(path_parts) > 1 else []
293
294 # Try direct API path first: dbbasic_admin.api.database
295 if remaining_parts:
296 module_path = f"{package_name}.api.{'.'.join(remaining_parts)}"
297 else:
298 # For /admin/ -> dbbasic_admin.api.__init__
299 module_path = f"{package_name}.api"
300
301 try:
302 module = importlib.import_module(module_path)
303 return load_and_call_package_handler(module, request)
304 except (ImportError, AttributeError):
305 pass
306
307 except ImportError:
308 pass
309
310 # If we have /admin/{package}/{path}, try dbbasic_{package} as fallback
311 # E.g., /admin/accounts/users -> dbbasic_accounts.api.accounts.users
312 if first_segment == 'admin' and len(path_parts) >= 2:
313 second_segment = path_parts[1]
314 package_name = f"dbbasic_{second_segment}"
315
316 try:
317 package = importlib.import_module(package_name)
318
319 # Build module path with all remaining parts
320 remaining_parts = path_parts[1:] # Include the package name in path
321 module_path = f"{package_name}.api.{'.'.join(remaining_parts)}"
322
323 try:
324 module = importlib.import_module(module_path)
325 return load_and_call_package_handler(module, request)
326 except (ImportError, AttributeError):
327 pass
328
329 except ImportError:
330 pass
331
332 return None
333
334
335def load_and_call_package_handler(module, request: dict, **kwargs):
336 """
337 Call handler from an imported package module.
338
339 Similar to load_and_call_handler but for already-imported modules.
340 """
341 try:
342 # Try method-specific function first (GET, POST, PUT, DELETE, etc.)
343 method = request.get("method", "GET")
344 method_handler = getattr(module, method, None)
345
346 if method_handler and callable(method_handler):
347 result = method_handler(request, **kwargs)
348 elif hasattr(module, "handle"):
349 # Fall back to generic handle() function
350 result = module.handle(request, **kwargs) if kwargs else module.handle(request)
351 else:
352 # No handler found
353 return None
354
355 # Support various return formats
356 if isinstance(result, tuple) and len(result) == 3:
357 return result
358 else:
359 return 500, [("content-type", "text/plain")], [b"Invalid handler return format"]
360
361 except Exception as e:
362 import traceback
363 tb = traceback.format_exc()
364 return 500, [("content-type", "text/plain")], [f"Package handler error: {e}\n\n{tb}".encode()]
365
366
367def load_and_call_handler(handler_file: Path, request: dict, **kwargs):
368 """
369 Load a Python module and call the appropriate handler function.
370
371 Supports two patterns:
372 1. Method-specific functions: GET(request, **kwargs), POST(request, **kwargs), etc.
373 2. Generic handle function: handle(request, **kwargs)
374
375 Method-specific functions take precedence. Falls back to handle() if method function doesn't exist.
376 """
377 try:
378 spec = importlib.util.spec_from_file_location("handler", handler_file)
379 if not spec or not spec.loader:
380 return 500, [("content-type", "text/plain")], [b"Failed to load handler"]
381
382 module = importlib.util.module_from_spec(spec)
383 spec.loader.exec_module(module)
384
385 # Try method-specific function first (GET, POST, PUT, DELETE, etc.)
386 method = request.get("method", "GET")
387 method_handler = getattr(module, method, None)
388
389 if method_handler and callable(method_handler):
390 result = method_handler(request, **kwargs)
391 elif hasattr(module, "handle"):
392 # Fall back to generic handle() function
393 result = module.handle(request, **kwargs) if kwargs else module.handle(request)
394 else:
395 # No handler found
396 return 405, [("content-type", "text/plain")], [b"Method Not Allowed"]
397
398 # Support various return formats
399 if isinstance(result, tuple) and len(result) == 3:
400 return result
401 else:
402 return 500, [("content-type", "text/plain")], [b"Invalid handler return format"]
403
404 except Exception as e:
405 import traceback
406 tb = traceback.format_exc()
407 return 500, [("content-type", "text/plain")], [f"Handler error: {e}\n\n{tb}".encode()]
408
409
410def try_template(path_parts: list[str]):
411 """Try to render a template"""
412 if not path_parts:
413 # Root: try index.html
414 template_name = "index.html"
415 else:
416 # Try exact path
417 template_name = "/".join(path_parts)
418 if not template_name.endswith(".html"):
419 template_name += ".html"
420
421 template_file = BASE_DIR / "templates" / template_name
422
423 if template_file.exists():
424 try:
425 rendered = render(template_name)
426 return html(rendered)
427 except Exception as e:
428 return 500, [("content-type", "text/plain")], [f"Template error: {e}".encode()]
429
430 return None