swiftpy-framework 0.1.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.
Files changed (211) hide show
  1. swiftpy/.gitignore +0 -0
  2. swiftpy/__init__.py +572 -0
  3. swiftpy/admin/__init__.py +50 -0
  4. swiftpy/admin/auth.py +522 -0
  5. swiftpy/admin/registry.py +567 -0
  6. swiftpy/admin/views.py +1583 -0
  7. swiftpy/ai/__init__.py +199 -0
  8. swiftpy/ai/_deterministic.py +40 -0
  9. swiftpy/ai/_fake.py +604 -0
  10. swiftpy/ai/agents/__init__.py +30 -0
  11. swiftpy/ai/agents/base_agent.py +506 -0
  12. swiftpy/ai/agents/memory.py +864 -0
  13. swiftpy/ai/client.py +1011 -0
  14. swiftpy/ai/conversation.py +171 -0
  15. swiftpy/ai/embeddings.py +321 -0
  16. swiftpy/ai/exceptions.py +75 -0
  17. swiftpy/ai/history_strategies.py +157 -0
  18. swiftpy/ai/middleware.py +918 -0
  19. swiftpy/ai/observability/__init__.py +28 -0
  20. swiftpy/ai/observability/drivers.py +763 -0
  21. swiftpy/ai/observability/observer.py +364 -0
  22. swiftpy/ai/pool.py +102 -0
  23. swiftpy/ai/pricing.py +101 -0
  24. swiftpy/ai/prompts/__init__.py +6 -0
  25. swiftpy/ai/prompts/loader.py +343 -0
  26. swiftpy/ai/providers/__init__.py +22 -0
  27. swiftpy/ai/providers/anthropic_provider.py +353 -0
  28. swiftpy/ai/providers/base.py +273 -0
  29. swiftpy/ai/providers/openai_provider.py +275 -0
  30. swiftpy/ai/rag/__init__.py +53 -0
  31. swiftpy/ai/rag/context_formatter.py +263 -0
  32. swiftpy/ai/rag/pipeline_builder.py +544 -0
  33. swiftpy/ai/rag/reranker.py +484 -0
  34. swiftpy/ai/rag/result.py +78 -0
  35. swiftpy/ai/rag/retriever.py +315 -0
  36. swiftpy/ai/redis_store.py +227 -0
  37. swiftpy/ai/streaming.py +115 -0
  38. swiftpy/ai/tools/__init__.py +22 -0
  39. swiftpy/ai/tools/base_tool.py +489 -0
  40. swiftpy/ai/tools/first_party.py +384 -0
  41. swiftpy/ai/tools/tool_loop.py +417 -0
  42. swiftpy/ai/vectorstore/__init__.py +46 -0
  43. swiftpy/ai/vectorstore/base.py +542 -0
  44. swiftpy/ai/vectorstore/chroma_adapter.py +435 -0
  45. swiftpy/ai/vectorstore/in_memory_adapter.py +321 -0
  46. swiftpy/ai/vectorstore/lancedb_adapter.py +370 -0
  47. swiftpy/ai/vectorstore/pgvector_adapter.py +496 -0
  48. swiftpy/ai/vectorstore/pinecone_adapter.py +445 -0
  49. swiftpy/ai/vectorstore/qdrant_adapter.py +418 -0
  50. swiftpy/auth/__init__.py +50 -0
  51. swiftpy/auth/api_key_guard.py +544 -0
  52. swiftpy/auth/auth_manager.py +259 -0
  53. swiftpy/auth/exceptions.py +71 -0
  54. swiftpy/auth/jwt_guard.py +230 -0
  55. swiftpy/auth/jwt_issuer.py +658 -0
  56. swiftpy/auth/token_blacklist.py +300 -0
  57. swiftpy/cache/__init__.py +14 -0
  58. swiftpy/cache/cache.py +251 -0
  59. swiftpy/cache/driver.py +216 -0
  60. swiftpy/cache/drivers/memory.py +199 -0
  61. swiftpy/cache/drivers/redis.py +421 -0
  62. swiftpy/console/__init__.py +0 -0
  63. swiftpy/console/cli.py +68 -0
  64. swiftpy/console/commands/__init__.py +0 -0
  65. swiftpy/console/commands/cache.py +164 -0
  66. swiftpy/console/commands/make.py +935 -0
  67. swiftpy/console/commands/migrate.py +280 -0
  68. swiftpy/console/commands/new.py +1806 -0
  69. swiftpy/console/commands/queue.py +306 -0
  70. swiftpy/console/commands/seed.py +252 -0
  71. swiftpy/console/commands/start.py +171 -0
  72. swiftpy/console/commands/storage.py +104 -0
  73. swiftpy/console/loader.py +21 -0
  74. swiftpy/console/stubs/__init__.py +26 -0
  75. swiftpy/console/stubs/controller.stub +14 -0
  76. swiftpy/console/stubs/event.stub +14 -0
  77. swiftpy/console/stubs/job.stub +22 -0
  78. swiftpy/console/stubs/listener.stub +14 -0
  79. swiftpy/console/stubs/mail.stub +20 -0
  80. swiftpy/console/stubs/middleware.stub +16 -0
  81. swiftpy/console/stubs/migration.alter.stub +17 -0
  82. swiftpy/console/stubs/migration.api_keys.stub +22 -0
  83. swiftpy/console/stubs/migration.blank.stub +11 -0
  84. swiftpy/console/stubs/migration.create.stub +15 -0
  85. swiftpy/console/stubs/migration.stub +11 -0
  86. swiftpy/console/stubs/migration.update.stub +17 -0
  87. swiftpy/console/stubs/model.stub +17 -0
  88. swiftpy/console/stubs/provider.stub +18 -0
  89. swiftpy/console/stubs/repository.stub +10 -0
  90. swiftpy/console/stubs/request.stub +16 -0
  91. swiftpy/console/stubs/resource.stub +21 -0
  92. swiftpy/console/stubs/schema.stub +12 -0
  93. swiftpy/console/stubs/seeder.stub +14 -0
  94. swiftpy/console/stubs/service.stub +10 -0
  95. swiftpy/core/__init__.py +0 -0
  96. swiftpy/core/application.py +1306 -0
  97. swiftpy/core/bootstrap.py +30 -0
  98. swiftpy/core/config.py +432 -0
  99. swiftpy/core/container.py +596 -0
  100. swiftpy/core/container_exceptions.py +18 -0
  101. swiftpy/core/context.py +148 -0
  102. swiftpy/core/exceptions.py +352 -0
  103. swiftpy/core/providers/base.py +35 -0
  104. swiftpy/database/__init__.py +41 -0
  105. swiftpy/database/exceptions.py +42 -0
  106. swiftpy/database/identifiers.py +105 -0
  107. swiftpy/database/migrations/__init__.py +36 -0
  108. swiftpy/database/migrations/blueprint.py +431 -0
  109. swiftpy/database/migrations/lock.py +104 -0
  110. swiftpy/database/migrations/migration.py +22 -0
  111. swiftpy/database/migrations/migrator.py +507 -0
  112. swiftpy/database/migrations/schema.py +435 -0
  113. swiftpy/database/orm/__init__.py +33 -0
  114. swiftpy/database/orm/fields.py +92 -0
  115. swiftpy/database/orm/model.py +2034 -0
  116. swiftpy/database/orm/registry.py +33 -0
  117. swiftpy/database/orm/relationships.py +836 -0
  118. swiftpy/database/pagination/__init__.py +16 -0
  119. swiftpy/database/pagination/contracts.py +60 -0
  120. swiftpy/database/pagination/paginator.py +112 -0
  121. swiftpy/database/pagination/simple_paginator.py +97 -0
  122. swiftpy/database/pool.py +218 -0
  123. swiftpy/database/query_builder.py +1803 -0
  124. swiftpy/database/seeder.py +39 -0
  125. swiftpy/database/transaction.py +276 -0
  126. swiftpy/events/__init__.py +10 -0
  127. swiftpy/events/dispatcher.py +308 -0
  128. swiftpy/events/redis_bus.py +552 -0
  129. swiftpy/filesystem/__init__.py +227 -0
  130. swiftpy/filesystem/disk.py +378 -0
  131. swiftpy/filesystem/drivers/__init__.py +11 -0
  132. swiftpy/filesystem/drivers/base.py +156 -0
  133. swiftpy/filesystem/drivers/local.py +559 -0
  134. swiftpy/filesystem/drivers/s3.py +655 -0
  135. swiftpy/filesystem/events.py +37 -0
  136. swiftpy/filesystem/exceptions.py +127 -0
  137. swiftpy/filesystem/manager.py +138 -0
  138. swiftpy/filesystem/metadata.py +22 -0
  139. swiftpy/filesystem/paths.py +99 -0
  140. swiftpy/filesystem/service_provider.py +17 -0
  141. swiftpy/filesystem/uploads/__init__.py +13 -0
  142. swiftpy/filesystem/uploads/handlers.py +362 -0
  143. swiftpy/filesystem/uploads/uploaded_file.py +222 -0
  144. swiftpy/filesystem/uploads/validators.py +186 -0
  145. swiftpy/filesystem/visibility.py +22 -0
  146. swiftpy/helpers/__init__.py +42 -0
  147. swiftpy/helpers/helper.py +180 -0
  148. swiftpy/http/exceptions.py +41 -0
  149. swiftpy/http/middleware.py +307 -0
  150. swiftpy/http/request.py +375 -0
  151. swiftpy/http/response.py +442 -0
  152. swiftpy/http/router.py +1050 -0
  153. swiftpy/mail/__init__.py +58 -0
  154. swiftpy/mail/attachments.py +255 -0
  155. swiftpy/mail/config.py +71 -0
  156. swiftpy/mail/envelope.py +183 -0
  157. swiftpy/mail/exceptions.py +90 -0
  158. swiftpy/mail/facade.py +312 -0
  159. swiftpy/mail/mailable.py +53 -0
  160. swiftpy/mail/manager.py +240 -0
  161. swiftpy/mail/message.py +186 -0
  162. swiftpy/mail/models.py +19 -0
  163. swiftpy/mail/queue/__init__.py +5 -0
  164. swiftpy/mail/queue/job.py +279 -0
  165. swiftpy/mail/service_provider.py +19 -0
  166. swiftpy/mail/templates/__init__.py +5 -0
  167. swiftpy/mail/templates/renderer.py +173 -0
  168. swiftpy/mail/transports/__init__.py +21 -0
  169. swiftpy/mail/transports/api/__init__.py +13 -0
  170. swiftpy/mail/transports/api/base.py +194 -0
  171. swiftpy/mail/transports/api/mailgun.py +158 -0
  172. swiftpy/mail/transports/api/resend.py +156 -0
  173. swiftpy/mail/transports/api/sendgrid.py +172 -0
  174. swiftpy/mail/transports/base.py +24 -0
  175. swiftpy/mail/transports/console.py +91 -0
  176. swiftpy/mail/transports/sendmail.py +128 -0
  177. swiftpy/mail/transports/smtp.py +466 -0
  178. swiftpy/queue/__init__.py +13 -0
  179. swiftpy/queue/dispatcher.py +813 -0
  180. swiftpy/queue/job.py +541 -0
  181. swiftpy/queue/worker.py +556 -0
  182. swiftpy/support/__init__.py +12 -0
  183. swiftpy/support/keys.py +108 -0
  184. swiftpy/support/redis_config.py +223 -0
  185. swiftpy/support/strings.py +114 -0
  186. swiftpy/testing/__init__.py +20 -0
  187. swiftpy/testing/fakes/__init__.py +11 -0
  188. swiftpy/testing/fakes/ai_fake.py +21 -0
  189. swiftpy/testing/fakes/vectorstore_fake.py +194 -0
  190. swiftpy/testing/fixtures.py +124 -0
  191. swiftpy/testing/http_client.py +730 -0
  192. swiftpy/testing/test_case.py +126 -0
  193. swiftpy/validation/__init__.py +97 -0
  194. swiftpy/validation/exceptions.py +26 -0
  195. swiftpy/validation/form_request.py +302 -0
  196. swiftpy/validation/protocols.py +33 -0
  197. swiftpy/validation/rules/__init__.py +89 -0
  198. swiftpy/validation/rules/builtin.py +391 -0
  199. swiftpy/validation/rules/exists.py +86 -0
  200. swiftpy/validation/rules/registry.py +290 -0
  201. swiftpy/validation/rules/required.py +55 -0
  202. swiftpy/validation/rules/unique.py +138 -0
  203. swiftpy/validation/validator.py +612 -0
  204. swiftpy/websockets/__init__.py +19 -0
  205. swiftpy/websockets/connection.py +317 -0
  206. swiftpy/websockets/manager.py +271 -0
  207. swiftpy_framework-0.1.0.dist-info/METADATA +603 -0
  208. swiftpy_framework-0.1.0.dist-info/RECORD +211 -0
  209. swiftpy_framework-0.1.0.dist-info/WHEEL +4 -0
  210. swiftpy_framework-0.1.0.dist-info/entry_points.txt +2 -0
  211. swiftpy_framework-0.1.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,362 @@
1
+ from __future__ import annotations
2
+
3
+ import asyncio
4
+ import posixpath
5
+ import re
6
+ import tempfile
7
+ from collections.abc import AsyncIterator, Callable
8
+ from pathlib import Path
9
+ from typing import Any
10
+
11
+ from swiftpy.filesystem.exceptions import (
12
+ FileTooLargeError,
13
+ MalformedMultipartError,
14
+ )
15
+ from swiftpy.filesystem.uploads.uploaded_file import UploadedFile
16
+ from swiftpy.http.exceptions import ClientDisconnect
17
+
18
+ _HEADER_SPLIT = b"\r\n\r\n"
19
+ _LINE_SPLIT = b"\r\n"
20
+
21
+
22
+ def _open_part_spool(
23
+ memory_limit: int,
24
+ temp_dir: str | None,
25
+ ) -> tempfile.SpooledTemporaryFile[bytes]:
26
+ return tempfile.SpooledTemporaryFile(max_size=memory_limit, dir=temp_dir)
27
+
28
+
29
+ def _sanitize_part_filename(raw_name: str) -> str:
30
+ """Normalize slashes, extract basename, and reject dot/control-char traversal."""
31
+ if "\x00" in raw_name or "\r" in raw_name or "\n" in raw_name:
32
+ raise MalformedMultipartError("Invalid control character in upload filename.")
33
+ normalized = raw_name.replace("\\", "/")
34
+ cleaned = posixpath.basename(normalized)
35
+ if cleaned in {"", ".", ".."}:
36
+ raise MalformedMultipartError("Invalid traversal segment in upload filename.")
37
+ return cleaned
38
+
39
+
40
+ class FormData:
41
+ """Container for parsed multipart form fields and uploaded files."""
42
+
43
+ def __init__(self) -> None:
44
+ self.fields: dict[str, str] = {}
45
+ self.fields_list: dict[str, list[str]] = {}
46
+ self.files: dict[str, UploadedFile] = {}
47
+ self.files_list: dict[str, list[UploadedFile]] = {}
48
+
49
+ def add_field(self, name: str, value: str) -> None:
50
+ self.fields[name] = value
51
+ self.fields_list.setdefault(name, []).append(value)
52
+
53
+ def add_file(self, name: str, file: UploadedFile) -> None:
54
+ self.files[name] = file
55
+ self.files_list.setdefault(name, []).append(file)
56
+
57
+ def get(self, name: str, default: Any = None) -> Any:
58
+ if name in self.fields:
59
+ return self.fields[name]
60
+ if name in self.files:
61
+ return self.files[name]
62
+ return default
63
+
64
+ def get_file(self, name: str) -> UploadedFile | None:
65
+ return self.files.get(name)
66
+
67
+ def get_files(self, name: str) -> list[UploadedFile]:
68
+ return list(self.files_list.get(name, []))
69
+
70
+ def all_files(self) -> list[UploadedFile]:
71
+ result: list[UploadedFile] = []
72
+ for flist in self.files_list.values():
73
+ result.extend(flist)
74
+ return result
75
+
76
+ async def close(self) -> None:
77
+ """Close and discard all spooled uploaded files."""
78
+ for flist in self.files_list.values():
79
+ for f in flist:
80
+ try:
81
+ await f.close()
82
+ except OSError:
83
+ pass
84
+ self.files.clear()
85
+ self.files_list.clear()
86
+
87
+
88
+ class MultipartParser:
89
+ """
90
+ Streaming multipart/form-data parser.
91
+ Enforces bounded memory via SpooledTemporaryFile and streaming size limits.
92
+ """
93
+
94
+ def __init__(
95
+ self,
96
+ boundary: bytes,
97
+ *,
98
+ max_file_size: int = 100 * 1024 * 1024,
99
+ max_request_size: int = 200 * 1024 * 1024,
100
+ memory_limit: int = 1024 * 1024,
101
+ max_field_size: int | None = None,
102
+ temp_dir: str | Path | None = None,
103
+ ) -> None:
104
+ self.boundary = boundary
105
+ self.delimiter = b"--" + boundary
106
+ self.close_delimiter = b"--" + boundary + b"--"
107
+ self.max_file_size = max_file_size
108
+ self.max_request_size = max_request_size
109
+ self.memory_limit = memory_limit
110
+ self.max_field_size = max_field_size if max_field_size is not None else memory_limit
111
+ self.temp_dir = str(temp_dir) if temp_dir is not None else None
112
+
113
+ @classmethod
114
+ def extract_boundary(cls, content_type: str) -> bytes:
115
+ match = re.search(r'boundary=(?:"([^"]+)"|([^;\s]+))', content_type, re.IGNORECASE)
116
+ if not match:
117
+ raise MalformedMultipartError("Missing or invalid multipart boundary in Content-Type header.")
118
+ boundary_str = match.group(1) or match.group(2)
119
+ return boundary_str.encode("latin-1")
120
+
121
+ async def parse(
122
+ self,
123
+ stream: AsyncIterator[bytes] | Callable[[], Any],
124
+ ) -> FormData:
125
+ form_data = FormData()
126
+ buffer = bytearray()
127
+ total_request_bytes = 0
128
+
129
+ # Current part state
130
+ part_headers: dict[str, str] = {}
131
+ part_name: str | None = None
132
+ part_filename: str | None = None
133
+ part_is_empty_file = False
134
+ part_content_type: str = "application/octet-stream"
135
+ part_spool: tempfile.SpooledTemporaryFile[bytes] | None = None
136
+ part_field_value: bytearray | None = None
137
+ part_file_bytes = 0
138
+ stream_eof = False
139
+
140
+ async def get_next_chunk() -> bytes | None:
141
+ nonlocal total_request_bytes, stream_eof
142
+ if stream_eof:
143
+ return None
144
+ chunk: bytes = b""
145
+ if isinstance(stream, AsyncIterator):
146
+ try:
147
+ chunk = await anext(stream)
148
+ except StopAsyncIteration:
149
+ stream_eof = True
150
+ return None
151
+ else:
152
+ msg = await stream()
153
+ if msg.get("type") == "http.disconnect":
154
+ raise ClientDisconnect("Client disconnected while reading multipart upload body.")
155
+ chunk = msg.get("body", b"")
156
+ if not chunk and not msg.get("more_body", False):
157
+ return None
158
+ if not msg.get("more_body", False):
159
+ stream_eof = True
160
+ if not chunk:
161
+ return None
162
+
163
+ if chunk:
164
+ total_request_bytes += len(chunk)
165
+ if total_request_bytes > self.max_request_size:
166
+ raise FileTooLargeError(
167
+ f"Request payload exceeds maximum allowed size of {self.max_request_size} bytes."
168
+ )
169
+ return chunk
170
+
171
+ try:
172
+ # Read until genuine initial delimiter (must be followed by CRLF or '--')
173
+ init_search_pos = 0
174
+ while True:
175
+ init_idx = buffer.find(self.delimiter, init_search_pos)
176
+ if init_idx != -1:
177
+ valid_prefix = init_idx == 0 or buffer[init_idx - 1 : init_idx] == b"\n"
178
+ after_init = init_idx + len(self.delimiter)
179
+ while len(buffer) < after_init + 2:
180
+ chunk = await get_next_chunk()
181
+ if chunk is None:
182
+ raise MalformedMultipartError(
183
+ "Stream ended before initial multipart boundary was found."
184
+ )
185
+ buffer.extend(chunk)
186
+ init_suffix = bytes(buffer[after_init : after_init + 2])
187
+ if valid_prefix and init_suffix in (b"--", b"\r\n"):
188
+ buffer = buffer[after_init:]
189
+ break
190
+ init_search_pos = init_idx + 2
191
+ continue
192
+ chunk = await get_next_chunk()
193
+ if chunk is None:
194
+ raise MalformedMultipartError(
195
+ "Stream ended before initial multipart boundary was found."
196
+ )
197
+ buffer.extend(chunk)
198
+
199
+ if buffer.startswith(b"--"):
200
+ return form_data
201
+
202
+ if buffer.startswith(b"\r\n"):
203
+ buffer = buffer[2:]
204
+
205
+ boundary_marker = b"\r\n" + self.delimiter
206
+ marker_len = len(boundary_marker)
207
+ guard_len = marker_len + 2
208
+
209
+ while True:
210
+ # Read part headers
211
+ while _HEADER_SPLIT not in buffer:
212
+ chunk = await get_next_chunk()
213
+ if chunk is None:
214
+ raise MalformedMultipartError("Unexpected end of stream while parsing part headers.")
215
+ buffer.extend(chunk)
216
+
217
+ header_end = buffer.find(_HEADER_SPLIT)
218
+ raw_headers = buffer[:header_end]
219
+ buffer = buffer[header_end + len(_HEADER_SPLIT) :]
220
+
221
+ part_headers.clear()
222
+ for line in raw_headers.split(_LINE_SPLIT):
223
+ if not line:
224
+ continue
225
+ colon_idx = line.find(b":")
226
+ if colon_idx != -1:
227
+ h_name = line[:colon_idx].decode("latin-1").strip().lower()
228
+ h_val = line[colon_idx + 1 :].decode("latin-1").strip()
229
+ part_headers[h_name] = h_val
230
+
231
+ cd = part_headers.get("content-disposition", "")
232
+ part_name = None
233
+ part_filename = None
234
+ part_is_empty_file = False
235
+ part_content_type = part_headers.get("content-type", "text/plain")
236
+
237
+ name_m = re.search(r'name="([^"]+)"', cd)
238
+ if name_m:
239
+ part_name = name_m.group(1)
240
+
241
+ filename_m = re.search(r'filename="([^"]*)"', cd)
242
+ if filename_m is not None:
243
+ raw_fname = filename_m.group(1)
244
+ if raw_fname == "":
245
+ part_is_empty_file = True
246
+ part_file_bytes = 0
247
+ else:
248
+ part_filename = _sanitize_part_filename(raw_fname)
249
+ part_spool = _open_part_spool(self.memory_limit, self.temp_dir)
250
+ part_file_bytes = 0
251
+ else:
252
+ part_field_value = bytearray()
253
+
254
+ # Read body of current part until genuine boundary_marker followed by '--' or CRLF
255
+ search_pos = 0
256
+ while True:
257
+ matched_idx = -1
258
+ while True:
259
+ delim_idx = buffer.find(boundary_marker, search_pos)
260
+ if delim_idx == -1:
261
+ break
262
+ after_idx = delim_idx + marker_len
263
+ while len(buffer) < after_idx + 2:
264
+ chunk = await get_next_chunk()
265
+ if chunk is None:
266
+ raise MalformedMultipartError(
267
+ "Unexpected end of stream: missing closing multipart boundary."
268
+ )
269
+ buffer.extend(chunk)
270
+ suffix = bytes(buffer[after_idx : after_idx + 2])
271
+ if suffix in (b"--", b"\r\n"):
272
+ matched_idx = delim_idx
273
+ break
274
+ search_pos = delim_idx + 2
275
+
276
+ if matched_idx != -1:
277
+ final_chunk = bytes(buffer[:matched_idx])
278
+ buffer = buffer[matched_idx + marker_len :]
279
+
280
+ if part_is_empty_file:
281
+ part_file_bytes += len(final_chunk)
282
+ if part_file_bytes > self.max_file_size:
283
+ raise FileTooLargeError(
284
+ f"Uploaded file exceeds maximum allowed size of {self.max_file_size} bytes."
285
+ )
286
+ elif part_spool is not None:
287
+ part_file_bytes += len(final_chunk)
288
+ if part_file_bytes > self.max_file_size:
289
+ raise FileTooLargeError(
290
+ f"Uploaded file '{part_filename}' exceeds maximum allowed size of {self.max_file_size} bytes."
291
+ )
292
+ await asyncio.to_thread(part_spool.write, final_chunk)
293
+ await asyncio.to_thread(part_spool.seek, 0)
294
+ up_file = UploadedFile(
295
+ file=part_spool,
296
+ filename=part_filename or "unnamed",
297
+ content_type=part_content_type,
298
+ size=part_file_bytes,
299
+ )
300
+ if part_name:
301
+ form_data.add_file(part_name, up_file)
302
+ part_spool = None
303
+ elif part_field_value is not None:
304
+ if len(part_field_value) + len(final_chunk) > self.max_field_size:
305
+ raise FileTooLargeError(
306
+ f"Form field '{part_name or ''}' exceeds maximum allowed size of {self.max_field_size} bytes."
307
+ )
308
+ part_field_value.extend(final_chunk)
309
+ val = part_field_value.decode("utf-8", errors="replace")
310
+ if part_name:
311
+ form_data.add_field(part_name, val)
312
+ part_field_value = None
313
+ break
314
+ else:
315
+ # Flush safe portion while retaining guard_len bytes to inspect future suffix
316
+ if len(buffer) > guard_len:
317
+ safe_len = len(buffer) - guard_len
318
+ safe_chunk = bytes(buffer[:safe_len])
319
+ buffer = buffer[safe_len:]
320
+
321
+ if part_is_empty_file:
322
+ part_file_bytes += len(safe_chunk)
323
+ if part_file_bytes > self.max_file_size:
324
+ raise FileTooLargeError(
325
+ f"Uploaded file exceeds maximum allowed size of {self.max_file_size} bytes."
326
+ )
327
+ elif part_spool is not None:
328
+ part_file_bytes += len(safe_chunk)
329
+ if part_file_bytes > self.max_file_size:
330
+ raise FileTooLargeError(
331
+ f"Uploaded file '{part_filename}' exceeds maximum allowed size of {self.max_file_size} bytes."
332
+ )
333
+ await asyncio.to_thread(part_spool.write, safe_chunk)
334
+ elif part_field_value is not None:
335
+ if len(part_field_value) + len(safe_chunk) > self.max_field_size:
336
+ raise FileTooLargeError(
337
+ f"Form field '{part_name or ''}' exceeds maximum allowed size of {self.max_field_size} bytes."
338
+ )
339
+ part_field_value.extend(safe_chunk)
340
+
341
+ search_pos = 0
342
+ chunk = await get_next_chunk()
343
+ if chunk is None:
344
+ raise MalformedMultipartError("Unexpected end of stream: missing closing multipart boundary.")
345
+ buffer.extend(chunk)
346
+
347
+ # Check if closing boundary
348
+ if buffer.startswith(b"--"):
349
+ break
350
+
351
+ if buffer.startswith(b"\r\n"):
352
+ buffer = buffer[2:]
353
+
354
+ return form_data
355
+ except BaseException:
356
+ await form_data.close()
357
+ if part_spool is not None:
358
+ try:
359
+ await asyncio.to_thread(part_spool.close)
360
+ except OSError:
361
+ pass
362
+ raise
@@ -0,0 +1,222 @@
1
+ from __future__ import annotations
2
+
3
+ import asyncio
4
+ import os
5
+ import posixpath
6
+ import shutil
7
+ import tempfile
8
+ from collections.abc import AsyncIterator, Mapping
9
+ from pathlib import Path
10
+ from typing import TYPE_CHECKING, Any
11
+
12
+ from swiftpy.filesystem.exceptions import PathTraversalError
13
+ from swiftpy.filesystem.manager import FilesystemManager
14
+ from swiftpy.filesystem.paths import PathNormalizer
15
+ from swiftpy.filesystem.uploads.validators import FileValidator
16
+
17
+ if TYPE_CHECKING:
18
+ from swiftpy.filesystem.disk import StorageDisk
19
+
20
+
21
+ def _sanitize_uploaded_filename(filename: str) -> str:
22
+ """Normalize '/' and '\\' separators, extract basename, and reject dot/null traversal."""
23
+ if "\x00" in filename:
24
+ raise PathTraversalError("Invalid null byte in uploaded filename.")
25
+ normalized = filename.replace("\\", "/")
26
+ cleaned = posixpath.basename(normalized).strip("\r\n")
27
+ if cleaned in {".", ".."}:
28
+ raise PathTraversalError(f"Path traversal detected in filename '{filename}'.")
29
+ return cleaned or "unnamed"
30
+
31
+
32
+ def _write_spooled_file_sync(
33
+ spool: tempfile.SpooledTemporaryFile[bytes],
34
+ dest_path: Path,
35
+ ) -> None:
36
+ """Synchronously copy a spooled upload to disk (executed in a worker thread)."""
37
+ dest_path.parent.mkdir(parents=True, exist_ok=True)
38
+ with open(dest_path, "wb") as out:
39
+ shutil.copyfileobj(spool, out)
40
+
41
+
42
+ def _resolve_contained_destination(
43
+ destination: str | Path,
44
+ filename: str,
45
+ base_dir: str | Path | None = None,
46
+ ) -> Path:
47
+ """Resolve destination path while rejecting null bytes, traversal segments, and escapes."""
48
+ dest_raw = str(destination)
49
+ if "\x00" in dest_raw:
50
+ raise PathTraversalError("Invalid null byte in upload save destination.")
51
+
52
+ raw_parts = dest_raw.replace("\\", "/").split("/")
53
+ if ".." in raw_parts:
54
+ raise PathTraversalError(
55
+ f"Path traversal segment '..' not allowed in destination '{destination}'."
56
+ )
57
+
58
+ candidate = Path(destination)
59
+ if base_dir is not None:
60
+ base_raw = str(base_dir)
61
+ if "\x00" in base_raw:
62
+ raise PathTraversalError("Invalid null byte in base directory.")
63
+ base_resolved = Path(base_dir).resolve()
64
+ target_resolved = (
65
+ candidate.resolve()
66
+ if candidate.is_absolute()
67
+ else (base_resolved / candidate).resolve()
68
+ )
69
+ if not target_resolved.is_relative_to(base_resolved) or target_resolved == base_resolved:
70
+ raise PathTraversalError(
71
+ f"Save destination '{destination}' escapes target directory '{base_dir}'."
72
+ )
73
+ raw_check = candidate if candidate.is_absolute() else (base_resolved / candidate)
74
+ if raw_check.is_symlink():
75
+ raise PathTraversalError(
76
+ f"Save destination '{destination}' cannot target a symlink."
77
+ )
78
+ return target_resolved
79
+
80
+ resolved = candidate.resolve()
81
+ if not candidate.is_absolute():
82
+ cwd = Path.cwd().resolve()
83
+ if not resolved.is_relative_to(cwd):
84
+ raise PathTraversalError(
85
+ f"Relative save destination '{destination}' escapes working directory."
86
+ )
87
+ if candidate.is_symlink():
88
+ raise PathTraversalError(f"Save destination '{destination}' cannot target a symlink.")
89
+
90
+ if resolved.exists() and resolved.is_dir():
91
+ safe_name = _sanitize_uploaded_filename(filename)
92
+ joined = (resolved / safe_name).resolve()
93
+ if not joined.is_relative_to(resolved) or joined == resolved:
94
+ raise PathTraversalError(
95
+ f"Save filename '{filename}' escapes target directory '{destination}'."
96
+ )
97
+ return joined
98
+
99
+ return resolved
100
+
101
+
102
+ class UploadedFile:
103
+ """
104
+ Represents an uploaded file received via an HTTP multipart request.
105
+ Backed by a SpooledTemporaryFile with bounded memory.
106
+ """
107
+
108
+ def __init__(
109
+ self,
110
+ file: tempfile.SpooledTemporaryFile[bytes],
111
+ filename: str,
112
+ content_type: str,
113
+ size: int,
114
+ ) -> None:
115
+ self._file = file
116
+ self._filename = filename
117
+ self._filename = _sanitize_uploaded_filename(filename) if filename else ""
118
+ self._content_type = content_type
119
+ self._size = size
120
+ self._extension = os.path.splitext(filename)[1].lstrip(".").lower()
121
+ self._extension = os.path.splitext(self._filename)[1].lstrip(".").lower()
122
+
123
+ @property
124
+ def filename(self) -> str:
125
+ """Original client-supplied filename (sanitized)."""
126
+ return self._filename
127
+
128
+ @property
129
+ def content_type(self) -> str:
130
+ """Content-Type declared in the HTTP multipart header."""
131
+ return self._content_type
132
+
133
+ @property
134
+ def size(self) -> int:
135
+ """Total size of the upload in bytes."""
136
+ return self._size
137
+
138
+ @property
139
+ def extension(self) -> str:
140
+ """Extracted file extension."""
141
+ return self._extension
142
+
143
+ async def get_real_size(self) -> int:
144
+ """
145
+ Return the actual byte size of the underlying spooled file,
146
+ preventing client metadata spoofing.
147
+ """
148
+ pos = await self.seek(0, os.SEEK_END)
149
+ await self.seek(0)
150
+ return pos
151
+
152
+ async def read(self, size: int = -1) -> bytes:
153
+ """Read bytes asynchronously from the spooled file."""
154
+ return await asyncio.to_thread(self._file.read, size)
155
+
156
+ async def seek(self, offset: int, whence: int = os.SEEK_SET) -> int:
157
+ """Seek asynchronously within the spooled file."""
158
+ return await asyncio.to_thread(self._file.seek, offset, whence)
159
+
160
+ async def chunks(self, chunk_size: int = 64 * 1024) -> AsyncIterator[bytes]:
161
+ """Stream the file content in chunks asynchronously."""
162
+ await self.seek(0)
163
+ while True:
164
+ chunk = await asyncio.to_thread(self._file.read, chunk_size)
165
+ if not chunk:
166
+ break
167
+ yield chunk
168
+
169
+ async def save(
170
+ self,
171
+ destination: str | Path,
172
+ base_dir: str | Path | None = None,
173
+ ) -> Path:
174
+ """
175
+ Save the uploaded file directly to a local filesystem path while enforcing
176
+ traversal and target-directory containment checks.
177
+ """
178
+ dest_path = _resolve_contained_destination(
179
+ destination,
180
+ filename=self._filename,
181
+ base_dir=base_dir,
182
+ )
183
+ await self.seek(0)
184
+ await asyncio.to_thread(_write_spooled_file_sync, self._file, dest_path)
185
+ return dest_path
186
+
187
+ async def store(self, directory: str = "", disk: str | None = None) -> str:
188
+ """
189
+ Store the uploaded file on the given disk with a generated random name.
190
+ Returns the resulting storage path.
191
+ """
192
+ name = PathNormalizer.generate_name(self.filename)
193
+ return await self.store_as(directory, name, disk=disk)
194
+
195
+ async def store_as(
196
+ self,
197
+ directory: str,
198
+ filename: str,
199
+ disk: str | None = None,
200
+ ) -> str:
201
+ """
202
+ Store the uploaded file on the given disk with an explicit filename.
203
+ Returns the resulting storage path.
204
+ """
205
+ clean_dir = PathNormalizer.normalize(directory) if directory else ""
206
+ clean_name = PathNormalizer.normalize(filename)
207
+ full_path = f"{clean_dir}/{clean_name}" if clean_dir else clean_name
208
+
209
+ await self.seek(0)
210
+ manager = FilesystemManager.get_instance()
211
+ target_disk: StorageDisk = manager.disk(disk)
212
+ await target_disk.write_stream(full_path, self.chunks())
213
+ return full_path
214
+
215
+ async def validate(self, rules: Mapping[str, Any]) -> None:
216
+ """Validate the upload against FileValidator rules."""
217
+ validator = FileValidator(rules)
218
+ await validator.validate(self)
219
+
220
+ async def close(self) -> None:
221
+ """Close and discard the spooled temporary file."""
222
+ await asyncio.to_thread(self._file.close)