constile-gate 0.6.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.
constile_gate/asgi.py ADDED
@@ -0,0 +1,318 @@
1
+ """
2
+ The gate as ASGI middleware (ASGI 3). It wraps any ASGI app, such as FastAPI,
3
+ Starlette, Quart, or Django's ASGI handler:
4
+
5
+ from constile_gate.asgi import ConstileMiddleware
6
+ app.add_middleware(ConstileMiddleware) # Starlette and FastAPI
7
+ application = ConstileMiddleware(application) # any ASGI app
8
+
9
+ It gets the page by calling the wrapped app in-process. People's requests go to
10
+ the app with the same scope, receive, and send, so their responses stream as
11
+ before. Network calls run in threads with a deadline, so the event loop never
12
+ waits on the network.
13
+ """
14
+ import asyncio
15
+ import logging
16
+ from urllib.parse import unquote, urlsplit
17
+
18
+ from . import _adapter
19
+ from .core import GATE_VERSION, ForwardOrigin, GateRequest, Headers, OriginHead, PassThrough, Respond, handle_gate
20
+ from .driver import HANDLED_KEY, call_with_deadline_async, run_async, spawn_background
21
+ from .transport import UrllibTransport
22
+
23
+ log = logging.getLogger("constile_gate")
24
+
25
+ # Extensions that let an app answer without body messages; a page the gate must read needs the bytes.
26
+ _UNREADABLE = ("http.response.pathsend", "http.response.zerocopy")
27
+ # What a release scope keeps from the visitor's: the ASGI spec's keys about the server and the
28
+ # connection, the lifespan state, and the app (Starlette sets it before any middleware runs). Never
29
+ # what outer middleware set for the visitor, such as "session" or "user".
30
+ _RELEASE_SCOPE_KEYS = ("type", "asgi", "http_version", "server", "client", "root_path", "extensions", "state", "app")
31
+ _DONE = object()
32
+
33
+
34
+ def request_from_scope(scope):
35
+ headers = []
36
+ cookies = []
37
+ for k, v in scope.get("headers") or []:
38
+ name, value = k.decode("latin-1").lower(), v.decode("latin-1")
39
+ if name == "cookie":
40
+ cookies.append(value)
41
+ else:
42
+ headers.append((name, value))
43
+ if cookies:
44
+ # HTTP/2 sends each cookie on its own line; one Cookie header joins them with "; ".
45
+ headers.append(("cookie", "; ".join(cookies)))
46
+ h = Headers(headers)
47
+ scheme = scope.get("scheme") or "http"
48
+ host = (h.get_all("host") or [None])[0]
49
+ if not host:
50
+ server = scope.get("server")
51
+ host = _adapter.host_with_port(server[0], server[1], scheme) if server else "localhost"
52
+ path = scope.get("path") or "/"
53
+ root = scope.get("root_path") or ""
54
+ if root and not (path == root or path.startswith(root + "/")):
55
+ # Servers before the ASGI spec said path includes root_path.
56
+ path = root + path
57
+ query = (scope.get("query_string") or b"").decode("latin-1")
58
+ url = "%s://%s%s%s" % (scheme, host, _adapter.quote_path(path.encode("utf-8")), "?" + query if query else "")
59
+ return GateRequest(scope.get("method", "GET"), url, h)
60
+
61
+
62
+ def _readable(s):
63
+ extensions = s.get("extensions")
64
+ if extensions:
65
+ s["extensions"] = {k: v for k, v in extensions.items() if k not in _UNREADABLE}
66
+ s[HANDLED_KEY] = GATE_VERSION
67
+ return s
68
+
69
+
70
+ def page_scope(scope):
71
+ """
72
+ The visitor's scope, for the page an agent's offer is for. Without Accept-Encoding, the app
73
+ answers uncompressed, so pages compressed with Brotli or Zstandard still get offers.
74
+ """
75
+ s = _readable(dict(scope))
76
+ s["headers"] = [(k, v) for k, v in scope.get("headers") or [] if k.lower() != b"accept-encoding"]
77
+ return s
78
+
79
+
80
+ def release_scope(scope, request):
81
+ """A fresh scope for the gate's own request to the app: the release URL, with only the gate's headers."""
82
+ u = urlsplit(request.url)
83
+ s = _readable({k: scope[k] for k in _RELEASE_SCOPE_KEYS if k in scope})
84
+ if isinstance(s.get("state"), dict):
85
+ s["state"] = dict(s["state"])
86
+ raw_path = u.path or "/"
87
+ headers = [(b"host", u.netloc.encode("latin-1"))] if u.netloc else []
88
+ headers += [(k.lower().encode("latin-1"), v.encode("latin-1")) for k, v in request.headers]
89
+ s.update(
90
+ {
91
+ "method": request.method,
92
+ "scheme": u.scheme or scope.get("scheme", "http"),
93
+ "path": unquote(raw_path),
94
+ "raw_path": raw_path.encode("utf-8"),
95
+ "query_string": u.query.encode("latin-1"),
96
+ "headers": headers,
97
+ }
98
+ )
99
+ return s
100
+
101
+
102
+ def release_receive(receive):
103
+ """The release request has no body; after that, the visitor's connection reports a disconnect as usual."""
104
+ sent = False
105
+
106
+ async def wrapped():
107
+ nonlocal sent
108
+ if not sent:
109
+ sent = True
110
+ return {"type": "http.request", "body": b"", "more_body": False}
111
+ return await receive()
112
+
113
+ return wrapped
114
+
115
+
116
+ def _header_bytes(headers):
117
+ return [(k.lower().encode("latin-1"), v.encode("latin-1")) for k, v in headers.items()]
118
+
119
+
120
+ class _AppCall:
121
+ """One call to the app, run as a task whose messages the gate reads, replays, or streams on."""
122
+
123
+ def __init__(self, app, scope, receive):
124
+ self._app, self._scope, self._receive = app, scope, receive
125
+ self._queue = asyncio.Queue(maxsize=16)
126
+ self.task = None
127
+ self.before = [] # messages the app sent before http.response.start
128
+ self.start = None
129
+ self.read = [] # messages after start, already taken from the app
130
+ self.complete = False
131
+
132
+ async def begin(self):
133
+ async def send(message):
134
+ await self._queue.put(message)
135
+
136
+ self.task = asyncio.ensure_future(self._app(self._scope, self._receive, send))
137
+ while self.start is None:
138
+ message = await self._next()
139
+ if message is _DONE:
140
+ await self.task
141
+ raise RuntimeError("the app returned without starting a response")
142
+ if message.get("type") == "http.response.start":
143
+ self.start = message
144
+ else:
145
+ self.before.append(message)
146
+ headers = Headers((k.decode("latin-1"), v.decode("latin-1")) for k, v in self.start.get("headers") or [])
147
+ return OriginHead(int(self.start["status"]), headers)
148
+
149
+ async def _next(self):
150
+ if not self._queue.empty():
151
+ return self._queue.get_nowait()
152
+ if self.task.done():
153
+ return _DONE
154
+ getter = asyncio.ensure_future(self._queue.get())
155
+ try:
156
+ await asyncio.wait({getter, self.task}, return_when=asyncio.FIRST_COMPLETED)
157
+ except BaseException:
158
+ getter.cancel()
159
+ raise
160
+ if getter.done():
161
+ return getter.result()
162
+ getter.cancel()
163
+ if not self._queue.empty():
164
+ return self._queue.get_nowait()
165
+ return _DONE
166
+
167
+ async def read_all(self):
168
+ """The body, as the app sent it. Stops at the last body message, so the app's background work doesn't hold the answer."""
169
+ trailers = bool(self.start.get("trailers"))
170
+ while not self.complete:
171
+ message = await self._next()
172
+ if message is _DONE:
173
+ self.task.result()
174
+ self.complete = True
175
+ break
176
+ self.read.append(message)
177
+ kind = message.get("type")
178
+ if kind == "http.response.body" and not message.get("more_body", False) and not trailers:
179
+ self.complete = True
180
+ elif kind == "http.response.trailers" and not message.get("more_trailers", False):
181
+ self.complete = True
182
+ return b"".join(m.get("body", b"") for m in self.read if m.get("type") == "http.response.body")
183
+
184
+ async def forward(self, send, headers=None, head_only=False):
185
+ start = dict(self.start)
186
+ if headers is not None:
187
+ start["headers"] = _header_bytes(headers)
188
+ for message in self.before:
189
+ await send(message)
190
+ await send(start)
191
+ if head_only:
192
+ await send({"type": "http.response.body", "body": b"", "more_body": False})
193
+ await self.finish()
194
+ return
195
+ for message in self.read:
196
+ await send(message)
197
+ while True:
198
+ message = await self._next()
199
+ if message is _DONE:
200
+ break
201
+ await send(message)
202
+ await self.task
203
+
204
+ async def finish(self):
205
+ """Lets the app run to its end (background tasks included), dropping anything it still sends."""
206
+ while await self._next() is not _DONE:
207
+ pass
208
+ await self.task
209
+
210
+ def cancel(self):
211
+ if self.task is not None and not self.task.done():
212
+ self.task.cancel()
213
+
214
+
215
+ class ConstileMiddleware:
216
+ """
217
+ Settings come from the arguments or the environment: CONSTILE_SITE_ID,
218
+ CONSTILE_SITE_SECRET, CONSTILE_NETWORK_URL, and optionally CONSTILE_TRUSTED_PROXIES,
219
+ CONSTILE_TIMEOUT, and CONSTILE_RETRY_AFTER. Without the first three, every request
220
+ passes through, with one warning when the middleware starts.
221
+
222
+ trusted_proxies: addresses or networks of proxies in front of the app.
223
+ Only then is X-Forwarded-For read, and only the part those proxies added.
224
+ timeout: seconds to wait for the network before serving the page anyway.
225
+ retry_after: after a failed config fetch, seconds to pass everything
226
+ through before asking the network again (CONSTILE_RETRY_AFTER, default 30).
227
+ transport: a callable that sends a NetworkCall and returns a NetworkReply;
228
+ it runs in a thread.
229
+ disabled: True turns the gate off, so every request goes to the app
230
+ unchanged. Defaults to CONSTILE_DISABLED (1, true, yes, or on), read on every
231
+ request.
232
+ """
233
+
234
+ platform = "asgi"
235
+
236
+ def __init__(
237
+ self,
238
+ app,
239
+ site_id=None,
240
+ secret=None,
241
+ network_url=None,
242
+ *,
243
+ trusted_proxies=None,
244
+ timeout=None,
245
+ retry_after=None,
246
+ platform=None,
247
+ transport=None,
248
+ settings=None,
249
+ disabled=None,
250
+ ):
251
+ self.app = app
252
+ self.disabled_option = disabled
253
+ if platform is not None:
254
+ self.platform = platform
255
+ self.settings = settings if settings is not None else _adapter.resolve_settings(site_id, secret, network_url, trusted_proxies, timeout, retry_after)
256
+ if self.settings is None:
257
+ _adapter.warn_missing()
258
+ self.transport = transport
259
+ return
260
+ self.transport = transport if transport is not None else UrllibTransport(self.settings.timeout)
261
+ self.options = self.settings.options(self.platform)
262
+
263
+ async def __call__(self, scope, receive, send):
264
+ if scope.get("type") != "http" or self.settings is None or scope.get(HANDLED_KEY) or _adapter.disabled(self.disabled_option):
265
+ await self.app(scope, receive, send)
266
+ return
267
+ scope[HANDLED_KEY] = GATE_VERSION
268
+ try:
269
+ request = request_from_scope(scope)
270
+ client = scope.get("client")
271
+ signals = _adapter.signals_for(client[0] if client else None, request.headers.get("x-forwarded-for"), self.settings.trusted_proxies)
272
+ except Exception: # noqa: BLE001 - a request the gate can't read goes to the app
273
+ log.exception("constile gate: can't read the request, passing through")
274
+ await self.app(scope, receive, send)
275
+ return
276
+
277
+ timeout = self.settings.timeout
278
+ calls = []
279
+
280
+ async def fetch_origin(req):
281
+ if req is None:
282
+ call = _AppCall(self.app, page_scope(scope), receive)
283
+ else:
284
+ call = _AppCall(self.app, release_scope(scope, req), release_receive(receive))
285
+ calls.append(call)
286
+ return await call.begin()
287
+
288
+ async def read_origin_body():
289
+ return await calls[-1].read_all()
290
+
291
+ try:
292
+ result = await run_async(
293
+ handle_gate(request, self.options, signals),
294
+ network=lambda c: call_with_deadline_async(self.transport, c, timeout),
295
+ fetch_origin=fetch_origin,
296
+ read_origin_body=read_origin_body,
297
+ background=lambda effect: spawn_background(effect, self.transport, timeout),
298
+ )
299
+ head_only = _adapter.head_only(request.method)
300
+
301
+ if isinstance(result, PassThrough):
302
+ await self.app(scope, receive, send)
303
+ elif isinstance(result, Respond):
304
+ headers = _header_bytes(result.headers) + [(b"content-length", str(len(result.body)).encode())]
305
+ await send({"type": "http.response.start", "status": result.status, "headers": headers})
306
+ await send({"type": "http.response.body", "body": b"" if head_only else result.body, "more_body": False})
307
+ for call in calls:
308
+ await call.finish()
309
+ elif isinstance(result, ForwardOrigin):
310
+ call = calls[-1]
311
+ if result.status is not None and result.status != call.start["status"]:
312
+ call.start = dict(call.start, status=result.status)
313
+ await call.forward(send, result.headers, head_only)
314
+ else:
315
+ raise TypeError("unknown gate result %r" % (result,))
316
+ finally:
317
+ for call in calls:
318
+ call.cancel()