prograph 1.3.3__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 (237) hide show
  1. prograph/__init__.py +36 -0
  2. prograph/__main__.py +5 -0
  3. prograph/_version.py +375 -0
  4. prograph/cli/__init__.py +1 -0
  5. prograph/cli/_iri_utils.py +124 -0
  6. prograph/cli/emit_genie_space.py +107 -0
  7. prograph/cli/generate_views.py +140 -0
  8. prograph/cli/main.py +420 -0
  9. prograph/cli/schema_inferrer.py +746 -0
  10. prograph/cli/ttl_loader.py +289 -0
  11. prograph/cli/upload_genie_space.py +84 -0
  12. prograph/config/__init__.py +27 -0
  13. prograph/config/yaml_config.py +848 -0
  14. prograph/demos/__init__.py +14 -0
  15. prograph/demos/turbofan/README.md +74 -0
  16. prograph/demos/turbofan/SCENARIO.md +209 -0
  17. prograph/demos/turbofan/__init__.py +75 -0
  18. prograph/demos/turbofan/create_tables.sql +206 -0
  19. prograph/demos/turbofan/data/engine-instances.ttl +1123 -0
  20. prograph/demos/turbofan/data/sensor-timeseries.csv +90 -0
  21. prograph/demos/turbofan/demo.py +162 -0
  22. prograph/demos/turbofan/genie_qa_notebook.py +434 -0
  23. prograph/demos/turbofan/graph.yaml +1098 -0
  24. prograph/demos/turbofan/instance_graph_demo.py +32 -0
  25. prograph/demos/turbofan/load.py +223 -0
  26. prograph/demos/turbofan/mapping.r2rml.ttl +991 -0
  27. prograph/demos/turbofan/ontology/engine-maintenance.ttl +606 -0
  28. prograph/demos/turbofan/payload-shapes.ttl +33 -0
  29. prograph/demos/turbofan/queries/example-queries.sparql +215 -0
  30. prograph/demos/turbofan/shapes.ttl +75 -0
  31. prograph/demos/turbofan/tables.py +106 -0
  32. prograph/demos/turbofan/turbofan_schema.py +393 -0
  33. prograph/demos/turbofan/validation_demo.py +153 -0
  34. prograph/describe.py +231 -0
  35. prograph/endpoint/__init__.py +12 -0
  36. prograph/endpoint/app.py +722 -0
  37. prograph/endpoint/cli.py +280 -0
  38. prograph/endpoint/credentials.py +240 -0
  39. prograph/endpoint/engines.py +418 -0
  40. prograph/endpoint/negotiate.py +101 -0
  41. prograph/endpoint/results.py +181 -0
  42. prograph/endpoint/service.py +31 -0
  43. prograph/engine.py +2718 -0
  44. prograph/execution.py +455 -0
  45. prograph/executors/__init__.py +6 -0
  46. prograph/executors/base.py +11 -0
  47. prograph/executors/databricks_sql_executor.py +51 -0
  48. prograph/executors/duckdb_executor.py +24 -0
  49. prograph/executors/mysql_executor.py +20 -0
  50. prograph/executors/oracle_executor.py +24 -0
  51. prograph/executors/pandas_executor.py +72 -0
  52. prograph/executors/postgresql_executor.py +35 -0
  53. prograph/executors/spark_executor.py +88 -0
  54. prograph/executors/sqlserver_executor.py +35 -0
  55. prograph/extras/__init__.py +1 -0
  56. prograph/extras/graphql/__init__.py +33 -0
  57. prograph/extras/graphql/execute.py +25 -0
  58. prograph/extras/graphql/schema.py +314 -0
  59. prograph/extras/instance_graph.py +559 -0
  60. prograph/genie/__init__.py +83 -0
  61. prograph/genie/databricks_uploader.py +306 -0
  62. prograph/genie/deploy.py +393 -0
  63. prograph/genie/formats.py +414 -0
  64. prograph/genie/instruction_generator.py +375 -0
  65. prograph/genie/sample_query_generator.py +256 -0
  66. prograph/genie/shacl_views.py +318 -0
  67. prograph/genie/space_emitter.py +329 -0
  68. prograph/genie/view_generator.py +628 -0
  69. prograph/genie/view_writer.py +172 -0
  70. prograph/graph/__init__.py +1 -0
  71. prograph/graph/ansi_session.py +348 -0
  72. prograph/graph/databricks_sql_graph.py +300 -0
  73. prograph/graph/drivers.py +143 -0
  74. prograph/graph/duckdb_graph.py +68 -0
  75. prograph/graph/mysql_graph.py +38 -0
  76. prograph/graph/oracle_graph.py +285 -0
  77. prograph/graph/pandas_graph.py +343 -0
  78. prograph/graph/postgresql_graph.py +644 -0
  79. prograph/graph/spark_graph.py +556 -0
  80. prograph/graph/sql_graph.py +83 -0
  81. prograph/graph/sqlserver_graph.py +72 -0
  82. prograph/hints.py +95 -0
  83. prograph/logging.py +550 -0
  84. prograph/mcp/__init__.py +29 -0
  85. prograph/mcp/__main__.py +180 -0
  86. prograph/mcp/bootstrap.py +98 -0
  87. prograph/mcp/server.py +601 -0
  88. prograph/mcp/sparql.py +397 -0
  89. prograph/mcp/tools.py +504 -0
  90. prograph/nlp/__init__.py +79 -0
  91. prograph/nlp/client.py +305 -0
  92. prograph/nlp/databricks_tools.py +369 -0
  93. prograph/nlp/graph_context.py +313 -0
  94. prograph/nlp/interface.py +652 -0
  95. prograph/nlp/prompts/__init__.py +19 -0
  96. prograph/nlp/prompts/examples.py +258 -0
  97. prograph/nlp/prompts/system.py +239 -0
  98. prograph/nlp/providers/__init__.py +14 -0
  99. prograph/nlp/providers/anthropic.py +274 -0
  100. prograph/nlp/providers/databricks.py +312 -0
  101. prograph/nlp/providers/openai.py +203 -0
  102. prograph/nlp/schema_context.py +78 -0
  103. prograph/ontology/__init__.py +53 -0
  104. prograph/ontology/alignment.py +542 -0
  105. prograph/ontology/hierarchy.py +310 -0
  106. prograph/ontology/imports.py +587 -0
  107. prograph/ontology/layer.py +991 -0
  108. prograph/ontology/skos.py +61 -0
  109. prograph/owl/__init__.py +27 -0
  110. prograph/owl/defined_classes.py +323 -0
  111. prograph/parameters.py +242 -0
  112. prograph/parser/__init__.py +1 -0
  113. prograph/parser/cypher/CypherLexer.py +836 -0
  114. prograph/parser/cypher/CypherListener.py +966 -0
  115. prograph/parser/cypher/CypherParser.py +10854 -0
  116. prograph/parser/cypher/CypherVisitor.py +543 -0
  117. prograph/parser/cypher/__init__.py +1 -0
  118. prograph/parser/sparql/SparqlLexer.py +801 -0
  119. prograph/parser/sparql/SparqlParser.py +10146 -0
  120. prograph/parser/sparql/SparqlParserListener.py +1056 -0
  121. prograph/parser/sparql/SparqlParserVisitor.py +593 -0
  122. prograph/parser/sparql/__init__.py +8 -0
  123. prograph/plan/__init__.py +3 -0
  124. prograph/plan/ir/__init__.py +1 -0
  125. prograph/plan/ir/casts.py +338 -0
  126. prograph/plan/ir/consistency.py +397 -0
  127. prograph/plan/ir/construct.py +90 -0
  128. prograph/plan/ir/cost.py +234 -0
  129. prograph/plan/ir/cypher_answer.py +1081 -0
  130. prograph/plan/ir/cypher_apoc.py +717 -0
  131. prograph/plan/ir/cypher_apoc_convert.py +505 -0
  132. prograph/plan/ir/cypher_apoc_date.py +845 -0
  133. prograph/plan/ir/cypher_apoc_map.py +496 -0
  134. prograph/plan/ir/cypher_apoc_meta.py +384 -0
  135. prograph/plan/ir/cypher_apoc_path.py +597 -0
  136. prograph/plan/ir/cypher_apoc_procedures.py +163 -0
  137. prograph/plan/ir/cypher_apoc_text.py +785 -0
  138. prograph/plan/ir/cypher_front.py +5474 -0
  139. prograph/plan/ir/cypher_functions.py +565 -0
  140. prograph/plan/ir/cypher_lists.py +935 -0
  141. prograph/plan/ir/cypher_maps.py +370 -0
  142. prograph/plan/ir/cypher_mixed.py +604 -0
  143. prograph/plan/ir/cypher_ontology.py +226 -0
  144. prograph/plan/ir/cypher_procedures.py +191 -0
  145. prograph/plan/ir/cypher_runtime_errors.py +107 -0
  146. prograph/plan/ir/cypher_temporal.py +1357 -0
  147. prograph/plan/ir/cypher_temporal_arith.py +339 -0
  148. prograph/plan/ir/cypher_values.py +546 -0
  149. prograph/plan/ir/cypher_write.py +612 -0
  150. prograph/plan/ir/dataset.py +643 -0
  151. prograph/plan/ir/dates.py +102 -0
  152. prograph/plan/ir/entry.py +992 -0
  153. prograph/plan/ir/expr.py +260 -0
  154. prograph/plan/ir/facts.py +1171 -0
  155. prograph/plan/ir/fresh.py +291 -0
  156. prograph/plan/ir/freshness.py +625 -0
  157. prograph/plan/ir/identity.py +797 -0
  158. prograph/plan/ir/java_datetime.py +265 -0
  159. prograph/plan/ir/java_regex.py +391 -0
  160. prograph/plan/ir/join_order.py +39 -0
  161. prograph/plan/ir/key_checks.py +433 -0
  162. prograph/plan/ir/keys.py +454 -0
  163. prograph/plan/ir/lower.py +5323 -0
  164. prograph/plan/ir/ops.py +619 -0
  165. prograph/plan/ir/owl_rl.py +1119 -0
  166. prograph/plan/ir/owl_rl_rules.py +725 -0
  167. prograph/plan/ir/profiles.py +694 -0
  168. prograph/plan/ir/ql.py +987 -0
  169. prograph/plan/ir/rdfs.py +342 -0
  170. prograph/plan/ir/rewrite.py +1782 -0
  171. prograph/plan/ir/saturate.py +339 -0
  172. prograph/plan/ir/semantics.py +103 -0
  173. prograph/plan/ir/slot.py +509 -0
  174. prograph/plan/ir/sparql_front.py +3418 -0
  175. prograph/plan/ir/strings.py +534 -0
  176. prograph/plan/ir/term_functions.py +274 -0
  177. prograph/plan/ir/terms.py +84 -0
  178. prograph/plan/ir/xpath_regex.py +264 -0
  179. prograph/plan/run_record.py +65 -0
  180. prograph/plan/sql/__init__.py +21 -0
  181. prograph/plan/sql/dialect.py +3726 -0
  182. prograph/plan/sql/mysql_serializer.py +103 -0
  183. prograph/plan/sql/names.py +65 -0
  184. prograph/plan/sql/oracle_serializer.py +306 -0
  185. prograph/plan/sql/pg_serializer.py +501 -0
  186. prograph/plan/sql/rel_algebra.py +781 -0
  187. prograph/plan/sql/sql_serializer.py +1419 -0
  188. prograph/plan/sql/sqlserver_serializer.py +603 -0
  189. prograph/provenance.py +222 -0
  190. prograph/r2rml/__init__.py +48 -0
  191. prograph/r2rml/catalog.py +259 -0
  192. prograph/r2rml/compile.py +372 -0
  193. prograph/r2rml/direct.py +140 -0
  194. prograph/r2rml/export.py +495 -0
  195. prograph/r2rml/model.py +180 -0
  196. prograph/r2rml/parser.py +546 -0
  197. prograph/r2rml/schema.py +120 -0
  198. prograph/read_only.py +122 -0
  199. prograph/results.py +157 -0
  200. prograph/rules/__init__.py +168 -0
  201. prograph/rules/__main__.py +32 -0
  202. prograph/schema/__init__.py +60 -0
  203. prograph/schema/change_set.py +50 -0
  204. prograph/schema/collations.py +198 -0
  205. prograph/schema/compile_schema.py +388 -0
  206. prograph/schema/context.py +845 -0
  207. prograph/schema/examples.py +234 -0
  208. prograph/schema/iri.py +817 -0
  209. prograph/schema/literals.py +94 -0
  210. prograph/schema/lpg_view.py +617 -0
  211. prograph/schema/mapping.py +1803 -0
  212. prograph/schema/maps_schema.py +40 -0
  213. prograph/schema/naming.py +77 -0
  214. prograph/schema/query_sources.py +59 -0
  215. prograph/schema/rows.py +215 -0
  216. prograph/schema/source_map.py +1103 -0
  217. prograph/schema/store_view.py +459 -0
  218. prograph/schema/types.py +569 -0
  219. prograph/schema/xsd.py +569 -0
  220. prograph/shacl/__init__.py +30 -0
  221. prograph/shacl/dqv.py +58 -0
  222. prograph/shacl/generate.py +255 -0
  223. prograph/shacl/report.py +138 -0
  224. prograph/shacl/validator.py +164 -0
  225. prograph/store.py +1737 -0
  226. prograph/utils/__init__.py +6 -0
  227. prograph/utils/exceptions.py +308 -0
  228. prograph/utils/helpers.py +126 -0
  229. prograph/warnings.py +46 -0
  230. prograph/writes.py +369 -0
  231. prograph-1.3.3.dist-info/METADATA +281 -0
  232. prograph-1.3.3.dist-info/RECORD +237 -0
  233. prograph-1.3.3.dist-info/WHEEL +5 -0
  234. prograph-1.3.3.dist-info/entry_points.txt +3 -0
  235. prograph-1.3.3.dist-info/licenses/LICENSE +201 -0
  236. prograph-1.3.3.dist-info/licenses/NOTICE +10 -0
  237. prograph-1.3.3.dist-info/top_level.txt +1 -0
@@ -0,0 +1,722 @@
1
+ """The SPARQL 1.1 Protocol over HTTP.
2
+
3
+ `create_app(engines, options)` is a FastAPI application with these routes:
4
+ `/sparql` (query, and the Service Description at GET with no query),
5
+ `/update` (SPARQL Update, always 403: ProGraph is read-only), `/healthz`,
6
+ `/queries/{id}/cancel` (cancel a running query by the id its /sparql response
7
+ names in `X-ProGraph-Query-Id`), and `/`, a page saying what the server is and how
8
+ to query it; and, given
9
+ an MCP server, `/mcp`, streamable
10
+ HTTP, under the same authentication.
11
+ `engines` gives the engine a request runs on (`EngineSource`): one engine
12
+ for the server, or one per signed-in user on a Databricks App
13
+ (`prograph.endpoint.engines`).
14
+ """
15
+
16
+
17
+ import itertools
18
+ import time
19
+ import uuid
20
+ from dataclasses import dataclass
21
+ from typing import Any, Callable, Iterator, List, Optional, Tuple
22
+
23
+ from prograph.endpoint import results as R
24
+ from prograph.endpoint.negotiate import choose
25
+ from prograph.endpoint.service import service_description
26
+
27
+ QUERY_FORM = "application/x-www-form-urlencoded"
28
+ # The header naming a /sparql query's id, the capability to cancel it (`POST /queries/{id}/cancel`):
29
+ # on every response once the query is registered; a request may send its own (a random uuid4) to
30
+ # cancel the query before its answer arrives.
31
+ QUERY_ID_HEADER = "X-ProGraph-Query-Id"
32
+ # A cancelled query's status. 409 Conflict, a registered status: the query's run was ended by a
33
+ # cancel, a state change made by another request. Not 499, which is nginx's own (unregistered) code
34
+ # for a client that closed its connection, which this client has not.
35
+ CANCELLED_STATUS = 409
36
+ QUERY_BODY = "application/sparql-query"
37
+ UPDATE_BODY = "application/sparql-update"
38
+
39
+
40
+ @dataclass
41
+ class Options:
42
+ """What a server allows. `row_cap` and `timeout` are off when None;
43
+ past either the answer is an error, never a truncated result."""
44
+ row_cap: Optional[int] = None
45
+ timeout: Optional[float] = None
46
+ endpoint_iri: str = "http://localhost:8000/sparql"
47
+ # A bearer token every request must carry; None is no authentication
48
+ # (the CLI requires one off localhost).
49
+ token: Optional[str] = None
50
+ # Per-user (`prograph serve --per-user`): each request's Authorization
51
+ # is its user's own credential, checked by the engine source; /mcp is
52
+ # then answered 401 before the MCP server reads a request without one.
53
+ per_user: bool = False
54
+ # With per_user: the identity provider MCP clients sign users in with,
55
+ # named in /.well-known/oauth-protected-resource (RFC 9728).
56
+ authorization_server: Optional[str] = None
57
+
58
+ def public_base(self) -> str:
59
+ """The server's public URL: `endpoint_iri` without its /sparql."""
60
+ iri = self.endpoint_iri.rstrip("/")
61
+ return iri[:-len("/sparql")] if iri.endswith("/sparql") else iri
62
+
63
+ def resource_metadata_url(self) -> Optional[str]:
64
+ """Where /mcp's Protected Resource Metadata is (RFC 9728 3.1: the
65
+ well-known path inserted before the resource's path), or None."""
66
+ if not (self.per_user and self.authorization_server):
67
+ return None
68
+ from urllib.parse import urlparse
69
+ base = urlparse(self.public_base())
70
+ return f"{base.scheme}://{base.netloc}/.well-known/oauth-protected-resource{base.path}/mcp"
71
+
72
+
73
+ class ProtocolError(Exception):
74
+ """An answer other than 200: its status and a plain-text reason."""
75
+
76
+ def __init__(self, status: int, reason: str, headers: Optional[dict] = None,
77
+ challenge: Optional[str] = None):
78
+ super().__init__(reason)
79
+ self.status = status
80
+ self.reason = reason
81
+ self.headers = headers or {}
82
+ # A 401's Bearer challenge parameters (RFC 6750 3), as
83
+ # 'error="invalid_token"'; none when no credential came.
84
+ self.challenge = challenge
85
+
86
+ def www_authenticate(self, resource_metadata: Optional[str] = None) -> str:
87
+ parts = [self.challenge] if self.challenge else []
88
+ if resource_metadata:
89
+ parts.append(f'resource_metadata="{resource_metadata}"')
90
+ return "Bearer" + (" " + ", ".join(parts) if parts else "")
91
+
92
+
93
+ class _Stop(Exception):
94
+ """A limit passed: a status before the first byte (500 for the row cap, 503 for the timeout),
95
+ the response aborted after it."""
96
+
97
+ def __init__(self, text: str, status: int = 500):
98
+ super().__init__(text)
99
+ self.status = status
100
+
101
+
102
+ # An engine for a request, or a ProtocolError (401 with no credentials).
103
+ EngineSource = Callable[[Any], Any]
104
+
105
+
106
+ def with_terms_hint(query: str) -> str:
107
+ """`query` with `terms=all` among its hints: every SELECT
108
+ variable a term struct. Only the first hint block is read
109
+ (`prograph.hints.parse_hints`), so a query with one gets it added there."""
110
+ from prograph.hints import HINT_BLOCK_PATTERN
111
+ match = HINT_BLOCK_PATTERN.search(query)
112
+ if match is None:
113
+ return "/*+ terms=all */ " + query
114
+ inner = match.group(1)
115
+ return query[:match.start(1)] + (inner + ", " if inner else "") + "terms=all" + query[match.end(1):]
116
+
117
+
118
+ def _refusal(error: Exception) -> Optional[ProtocolError]:
119
+ """The status an engine error answers with."""
120
+ from prograph.parameters import ParameterError
121
+ from prograph.plan.ir.sparql_front import QueryError
122
+ from prograph.utils.exceptions import SQLGenerationError, SQLRuntimeError
123
+ if isinstance(error, (QueryError, SQLGenerationError, ParameterError, NotImplementedError)):
124
+ return ProtocolError(400, f"{type(error).__name__}: {error}")
125
+ from prograph.execution import QueryCancelledException
126
+ if isinstance(error, QueryCancelledException):
127
+ return ProtocolError(CANCELLED_STATUS, "the query was cancelled (POST /queries/{id}/cancel)")
128
+ from prograph.utils.exceptions import is_statement_timeout
129
+ if is_statement_timeout(error):
130
+ # The database stopped it at the server's timeout: 503, as Fuseki answers a timeout.
131
+ return ProtocolError(503, f"the query passed the timeout: {error}")
132
+ if isinstance(error, SQLRuntimeError):
133
+ return ProtocolError(500, f"SQLRuntimeError: {error}")
134
+ return None
135
+
136
+
137
+ def _charset(content_type: str) -> str:
138
+ """The charset a Content-Type names, UTF-8 when it names none."""
139
+ for part in content_type.split(";")[1:]:
140
+ key, _, value = part.strip().partition("=")
141
+ if key.lower() == "charset":
142
+ return value.strip().strip('"').lower()
143
+ return "utf-8"
144
+
145
+
146
+ def _log(event: str, **fields: Any) -> None:
147
+ from prograph.logging import get_logger
148
+ get_logger("prograph.endpoint").info(event, **fields)
149
+
150
+
151
+ class Query:
152
+ """One query request through the Protocol, run on `engine`."""
153
+
154
+ def __init__(self, engine: Any, text: str, accept: str, fmt: List[str], options: Options,
155
+ context: Any = None, dataset: Any = None):
156
+ self.engine, self.text, self.options = engine, text, options
157
+ self.dataset = dataset # (default-graph-uri values, named-graph-uri values), or None
158
+ self.accept, self.fmt = accept, fmt
159
+ # The id logs name the query by; never the context's id, which cancels it.
160
+ self.id = uuid.uuid4().hex[:12]
161
+ self.context = context
162
+ self.started = time.monotonic()
163
+
164
+ def _check_time(self) -> None:
165
+ limit = self.options.timeout
166
+ if limit is not None and time.monotonic() - self.started > limit:
167
+ raise _Stop(f"query {self.id} passed the timeout of {limit} s", status=503)
168
+
169
+ def form(self) -> str:
170
+ """'solutions', 'boolean' or 'graph', from the query's parse alone
171
+ (`query_form`): the engine plans it once, in `execute`."""
172
+ from prograph.plan.ir.sparql_front import query_form
173
+ try:
174
+ form = query_form(self.text)
175
+ except Exception as error: # noqa: BLE001
176
+ refused = _refusal(error)
177
+ if refused is None:
178
+ raise
179
+ raise refused from error
180
+ if form == "update":
181
+ raise ProtocolError(400, "an update is sent to the update endpoint (/update), "
182
+ "not as a query (SPARQL 1.1 Protocol 2.2)")
183
+ return {"ask": "boolean", "construct": "graph", "describe": "graph"}.get(form, "solutions")
184
+
185
+ def run(self) -> Tuple[int, str, Any]:
186
+ """(status, media type, body): a str, bytes, or an iterator of str.
187
+ Everything before the first SELECT batch happens here, so an error
188
+ until then is a status."""
189
+ form = self.form()
190
+ if form == "graph":
191
+ media = choose(self.accept, self.fmt, list(R.GRAPH_TYPES), default="text/turtle")
192
+ elif form == "boolean":
193
+ media = choose(self.accept, self.fmt, list(R.BOOLEAN_TYPES), default=R.JSON)
194
+ else:
195
+ media = choose(self.accept, self.fmt, list(R.SOLUTION_TYPES), default=R.JSON)
196
+ if media is None:
197
+ kind = {"graph": "a CONSTRUCT", "boolean": "an ASK"}.get(form, "a SELECT")
198
+ asked = ", ".join(f"format={f}" for f in self.fmt) + ("; " if self.fmt else "")
199
+ raise ProtocolError(406, f"no result format of {kind} matches {asked}Accept: {self.accept}")
200
+ from prograph.execution import statement_deadline
201
+ try:
202
+ # The statement ProGraph starts is cancelled at the timeout, queued or running.
203
+ with statement_deadline(self.options.timeout):
204
+ running = {"context": self.context} if self.context is not None else {}
205
+ if self.dataset is not None:
206
+ running["dataset"] = self.dataset
207
+ if form == "graph":
208
+ graph = self.engine.execute(self.text, language="sparql", **running)
209
+ self._check_time()
210
+ self._done(form, len(graph))
211
+ return 200, media, R.write_graph(graph, media)
212
+ if form == "boolean":
213
+ rows = self.engine.execute(self.text, language="sparql", return_type="list", **running)
214
+ self._check_time()
215
+ self._done(form, 1)
216
+ return 200, media, R.write_boolean(media, bool(rows and rows[0].get("boolean")))
217
+ reader = self.engine.execute(with_terms_hint(self.text), language="sparql",
218
+ return_type="batches", **running)
219
+ names = list(reader.schema.names)
220
+ batches = iter(reader)
221
+ first = next(batches, None)
222
+ self._check_time()
223
+ cap = self.options.row_cap
224
+ if first is not None and cap is not None and first.num_rows > cap:
225
+ # Past the cap before a byte is sent: a status, not a cut.
226
+ raise _Stop(f"query {self.id} passed the row cap of {cap}")
227
+ except _Stop as stop:
228
+ raise ProtocolError(stop.status, str(stop)) from None
229
+ except ProtocolError:
230
+ raise
231
+ except TimeoutError as error:
232
+ raise ProtocolError(503, f"query {self.id} passed the timeout of {self.options.timeout} s: {error}") from None
233
+ except Exception as error: # noqa: BLE001
234
+ refused = _refusal(error)
235
+ if refused is None:
236
+ raise
237
+ raise refused from error
238
+ held = [] if first is None else [first]
239
+ return 200, media, self._stream(media, names, itertools.chain(held, batches))
240
+
241
+ def _stream(self, media: str, names: List[str], batches: Iterator[Any]) -> Iterator[str]:
242
+ count = 0
243
+ cap = self.options.row_cap
244
+
245
+ def rows():
246
+ nonlocal count
247
+ for batch in batches:
248
+ self._check_time()
249
+ for row in R.solutions([batch]):
250
+ count += 1
251
+ if cap is not None and count > cap:
252
+ raise _Stop(f"query {self.id} passed the row cap of {cap}")
253
+ yield row
254
+ try:
255
+ yield from R.SOLUTION_WRITERS[media](names, rows())
256
+ except Exception as error:
257
+ # After the first byte: the response is cut, never closed as a
258
+ # well-formed partial answer.
259
+ _log("sparql_endpoint_aborted", id=self.id, rows=count, reason=str(error)[:500])
260
+ raise
261
+ self._done("solutions", count)
262
+
263
+ def _done(self, form: str, rows: int) -> None:
264
+ # execute() logs the statement's SQL, or why it fell back, itself.
265
+ _log("sparql_endpoint_query", id=self.id, form=form, rows=rows,
266
+ ms=round((time.monotonic() - self.started) * 1000),
267
+ row_cap=self.options.row_cap, timeout=self.options.timeout)
268
+
269
+
270
+ EXAMPLE_QUERY = "SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10"
271
+
272
+
273
+ def landing_page(options: Options) -> str:
274
+ """The page at `/`: what the server is, its query URL and how to call
275
+ it. Links are relative to the page, so they hold behind a proxy that
276
+ serves the app at another address (a Databricks App's), where the
277
+ configured `endpoint_iri` names the address the server binds."""
278
+ from html import escape
279
+ from urllib.parse import quote
280
+ example = "sparql?query=" + quote(EXAMPLE_QUERY, safe="")
281
+ update = "SPARQL Update is refused: ProGraph is read-only over the data it maps."
282
+ limits = []
283
+ if options.row_cap is not None:
284
+ limits.append(f"a SELECT past {options.row_cap} rows is an error")
285
+ if options.timeout is not None:
286
+ limits.append(f"a query past {options.timeout:g} s is an error")
287
+ return f"""<!doctype html>
288
+ <html lang="en"><head><meta charset="utf-8"><title>ProGraph SPARQL endpoint</title>
289
+ <style>body{{font-family:system-ui,sans-serif;max-width:46rem;margin:2rem auto;padding:0 1rem;line-height:1.5}}
290
+ code,pre{{background:#f4f4f4;padding:.1rem .3rem}}pre{{padding:.6rem;overflow-x:auto}}</style></head>
291
+ <body>
292
+ <h1>ProGraph SPARQL endpoint</h1>
293
+ <p>A SPARQL 1.1 Protocol endpoint. ProGraph translates each query to the database's SQL
294
+ and runs it there.</p>
295
+ <h2>Query</h2>
296
+ <p>The query URL is <a href="sparql"><code>sparql</code></a> below this page: GET with a
297
+ <code>query</code> parameter, or POST a form or an <code>application/sparql-query</code> body.</p>
298
+ <p>An example: <a href="{escape(example)}"><code>{escape(EXAMPLE_QUERY)}</code></a>
299
+ (<a href="{escape(example)}&amp;format=csv">as CSV</a>).</p>
300
+ <p>Results are SPARQL JSON unless the <code>Accept</code> header or <code>format=</code> asks
301
+ for XML, CSV or TSV; a CONSTRUCT is Turtle, N-Triples, RDF/XML or JSON-LD.</p>
302
+ <pre>curl -H 'Accept: application/sparql-results+json' --data-urlencode 'query={escape(EXAMPLE_QUERY)}' &lt;this address&gt;/sparql</pre>
303
+ <p>{update}{(" Limits: " + "; ".join(limits) + ".") if limits else ""}</p>
304
+ <h2>More</h2>
305
+ <p><a href="sparql">The service description</a> (<code>sparql</code> with no query, in Turtle)
306
+ lists the result formats. <a href="healthz"><code>healthz</code></a> answers <code>ok</code>.</p>
307
+ </body></html>
308
+ """
309
+
310
+
311
+ def create_app(engines: EngineSource, options: Optional[Options] = None, mcp: Any = None,
312
+ queries: Any = None) -> Any:
313
+ """The application. `queries` holds the running queries by id
314
+ (`prograph.execution.RunningQueries`; one of its own by default), shared
315
+ with the MCP server's `cancel_query` where `prograph serve` builds both.
316
+ `mcp` is a FastMCP server (`prograph.mcp.server.
317
+ build_sparql_server`) served at `/mcp`: its session manager runs in the
318
+ application's lifespan, and the server's token, where it has one, is
319
+ required there as at `/sparql`. On a Databricks
320
+ App its tools run on the signed-in user's engine, from the same
321
+ `engines`."""
322
+ import contextlib
323
+ from fastapi import FastAPI, Request
324
+ from fastapi.concurrency import run_in_threadpool
325
+ from fastapi.responses import HTMLResponse, PlainTextResponse, Response, StreamingResponse
326
+
327
+ from prograph.execution import RunningQueries
328
+ import logging
329
+ # An access log names each request's path, a cancel's id among them: written as <id>, for the
330
+ # server `prograph serve` runs and an application that serves this one itself.
331
+ access = logging.getLogger("uvicorn.access")
332
+ if not any(isinstance(f, HideQueryIds) for f in access.filters):
333
+ access.addFilter(HideQueryIds())
334
+ options = options or Options()
335
+ queries = queries if queries is not None else RunningQueries()
336
+ mcp_app = mcp.streamable_http_app() if mcp is not None else None
337
+
338
+ @contextlib.asynccontextmanager
339
+ async def lifespan(app: Any) -> Any:
340
+ try:
341
+ if mcp is None:
342
+ yield
343
+ return
344
+ async with mcp.session_manager.run():
345
+ yield
346
+ finally:
347
+ # Per-user engines, their connections and the tokens in them
348
+ # go when the server does.
349
+ close = getattr(engines, "close", None)
350
+ if callable(close):
351
+ close()
352
+
353
+ app = FastAPI(title="ProGraph SPARQL endpoint", docs_url=None, redoc_url=None, openapi_url=None,
354
+ lifespan=lifespan)
355
+
356
+ def failure(error: ProtocolError, context: Any = None) -> Response:
357
+ _log("sparql_endpoint_refused", status=error.status, reason=error.reason[:300])
358
+ headers = dict(error.headers)
359
+ if context is not None:
360
+ headers[QUERY_ID_HEADER] = context.query_id
361
+ if error.status == 401:
362
+ headers["WWW-Authenticate"] = error.www_authenticate()
363
+ return PlainTextResponse(error.reason + "\n", status_code=error.status, headers=headers or None)
364
+
365
+ async def parameters(request: Request, body_type: str, field: str) -> Tuple[Optional[str], Any]:
366
+ """The operation's text and the request's parameters (GET's query
367
+ string, or the form), by SPARQL 1.1 Protocol 2.1 and 2.2."""
368
+ params = request.query_params
369
+ ctype = request.headers.get("content-type", "").split(";")[0].strip().lower()
370
+ if request.method == "POST":
371
+ if ctype == QUERY_FORM:
372
+ form = await request.form()
373
+ values = form.getlist(field)
374
+ if len(values) > 1:
375
+ raise ProtocolError(400, f"more than one '{field}' parameter")
376
+ return (values[0] if values else None), form
377
+ if ctype == body_type:
378
+ charset = _charset(request.headers.get("content-type", ""))
379
+ if charset not in ("utf-8", "utf8"):
380
+ raise ProtocolError(415, f"the body is UTF-8 (SPARQL 1.1 Protocol 2.1.3), not {charset}")
381
+ try:
382
+ return (await request.body()).decode("utf-8"), params
383
+ except UnicodeDecodeError:
384
+ raise ProtocolError(400, "the body is not UTF-8 (SPARQL 1.1 Protocol 2.1.3)") from None
385
+ raise ProtocolError(415, f"POST takes {QUERY_FORM} or {body_type}, not '{ctype}'")
386
+ values = params.getlist(field)
387
+ if len(values) > 1:
388
+ raise ProtocolError(400, f"more than one '{field}' parameter")
389
+ return (values[0] if values else None), params
390
+
391
+ def authorize(request: Request) -> None:
392
+ if options.token is None:
393
+ return
394
+ import hmac
395
+ given = request.headers.get("authorization", "")
396
+ if not hmac.compare_digest(given.encode(), f"Bearer {options.token}".encode()):
397
+ raise ProtocolError(401, "a bearer token is required")
398
+
399
+ def formats_of(params: Any) -> List[str]:
400
+ """Every `format=` and `output=` value, in order (SPARQLWrapper
401
+ sends both, and sometimes two of one)."""
402
+ return list(params.getlist("format")) + list(params.getlist("output"))
403
+
404
+ def dataset_of(params: Any) -> Any:
405
+ """The request's dataset (SPARQL 1.1 Protocol 2.1.4): `default-graph-uri` values merged into the
406
+ default graph, `named-graph-uri` values the named graphs, used in place of the query's own FROM
407
+ clauses; None where the request names none. An update's `using-graph-uri` is refused."""
408
+ for name in ("using-graph-uri", "using-named-graph-uri"):
409
+ if params.get(name):
410
+ raise ProtocolError(400, f"'{name}' is not supported: it belongs to an update "
411
+ "(SPARQL 1.1 Protocol 2.2.3), and 1.0 is read-only")
412
+ default, named = params.getlist("default-graph-uri"), params.getlist("named-graph-uri")
413
+ return (tuple(default), tuple(named)) if default or named else None
414
+
415
+ @app.get("/healthz")
416
+ def healthz() -> Response:
417
+ return PlainTextResponse("ok\n")
418
+
419
+ @app.get("/")
420
+ def landing() -> Response:
421
+ # A browser opening the server's address (a Databricks App's link)
422
+ # asked for `/` and got FastAPI's `{"detail": "Not Found"}`. The
423
+ # page holds no data, as /healthz does not, so it needs no token.
424
+ return HTMLResponse(landing_page(options))
425
+
426
+ @app.api_route("/sparql", methods=["GET", "POST"])
427
+ @app.api_route("/sparql/", methods=["GET", "POST"], include_in_schema=False)
428
+ async def sparql(request: Request) -> Response:
429
+ context = None
430
+ engine = None
431
+ try:
432
+ authorize(request)
433
+ # Registered at once, before the request is read and its engine opened, so a cancel
434
+ # sent as soon as the query is (by an id the client chose) is never a 404; closed below
435
+ # however the request ends.
436
+ try:
437
+ context = queries.open(request.headers.get(QUERY_ID_HEADER))
438
+ except ValueError as error:
439
+ raise ProtocolError(400, f"{QUERY_ID_HEADER}: {error}") from None
440
+ text, params = await parameters(request, QUERY_BODY, "query")
441
+ accept = request.headers.get("accept", "*/*")
442
+ if text is None:
443
+ if request.method == "POST" or params.get("update"):
444
+ raise ProtocolError(400, "no 'query' parameter")
445
+ media = choose(accept, formats_of(params), ["text/turtle", "application/rdf+xml"],
446
+ default="text/turtle")
447
+ if media is None:
448
+ raise ProtocolError(406, f"the service description is Turtle or RDF/XML, not {accept}")
449
+ queries.close(context)
450
+ graph = service_description(options, engines(request) if getattr(engines, "single", False) else None)
451
+ return Response(R.write_graph(graph, media), media_type=media)
452
+ dataset = dataset_of(params)
453
+ # Off the event loop: opening a user's connection and building
454
+ # an engine blocks, and the loop serves every other request.
455
+ engine = await run_in_threadpool(engines, request)
456
+ status, media, body = await run_in_threadpool(
457
+ Query(engine, text, accept, formats_of(params), options, context, dataset).run)
458
+ except BaseException as error:
459
+ if context is not None:
460
+ queries.close(context)
461
+ if engine is not None:
462
+ release(engines, engine)
463
+ if isinstance(error, ProtocolError):
464
+ return failure(error, context)
465
+ raise
466
+ named = {QUERY_ID_HEADER: context.query_id}
467
+ if isinstance(body, (str, bytes)):
468
+ queries.close(context)
469
+ release(engines, engine)
470
+ return Response(body, status_code=status, media_type=media, headers=named)
471
+ once = _ReleaseOnce(engines, engine, then=lambda: queries.close(context))
472
+ return _ReleasingStream(once, _released_after(body, once), status_code=status,
473
+ media_type=media, headers=named)
474
+
475
+ @app.post("/queries/{query_id}/cancel")
476
+ async def cancel(request: Request, query_id: str) -> Response:
477
+ # The id is the capability (a random uuid4 only its query's caller was given); the request
478
+ # is authenticated as /sparql's is. 202 when a running query is cancelled; 404 otherwise,
479
+ # an ended query unchanged. The id is not logged.
480
+ try:
481
+ authorize(request)
482
+ engine = await run_in_threadpool(engines, request)
483
+ release(engines, engine)
484
+ except ProtocolError as error:
485
+ return failure(error)
486
+ found = await run_in_threadpool(queries.cancel, query_id)
487
+ _log("sparql_endpoint_cancel", found=found)
488
+ if found:
489
+ return PlainTextResponse("cancelled: the query stops and answers 409\n", status_code=202)
490
+ return PlainTextResponse("no running query has this id\n", status_code=404)
491
+
492
+ @app.post("/update")
493
+ @app.post("/update/", include_in_schema=False)
494
+ async def update(request: Request) -> Response:
495
+ # ProGraph is read-only over the data it maps: every update
496
+ # is refused, before its body is read. The Protocol lets a service
497
+ # refuse an operation it does not perform with a 4XX status.
498
+ try:
499
+ authorize(request)
500
+ from prograph.read_only import message
501
+ raise ProtocolError(403, message("a SPARQL Update"))
502
+ except ProtocolError as error:
503
+ return failure(error)
504
+
505
+ metadata_url = options.resource_metadata_url() if mcp_app is not None else None
506
+ if metadata_url is not None:
507
+ from fastapi.responses import JSONResponse
508
+ from urllib.parse import urlparse
509
+ document = protected_resource_metadata(options)
510
+
511
+ def metadata() -> Response:
512
+ return JSONResponse(document, headers={"Cache-Control": "max-age=3600"})
513
+ # RFC 9728 3.1's path for the resource /mcp, and the root, which an
514
+ # MCP client asks next when it has no WWW-Authenticate to follow.
515
+ for path in sorted({urlparse(metadata_url).path, "/.well-known/oauth-protected-resource"}):
516
+ app.add_api_route(path, metadata, methods=["GET"], include_in_schema=False)
517
+
518
+ if mcp_app is not None:
519
+ # After the routes above, which match first: the MCP app answers its
520
+ # own path, /mcp, and nothing else.
521
+ guarded = (_user_guard(mcp_app, engines, metadata_url, options.authorization_server)
522
+ if options.per_user
523
+ else bearer_guard(mcp_app, options.token))
524
+ app.mount("/", _own_methods(app, guarded))
525
+ return app
526
+
527
+
528
+ class HideQueryIds:
529
+ """A logging filter that writes a cancel's path as `/queries/<id>/cancel`: an access log
530
+ (uvicorn's) names every request's path, and a query's id is the capability to cancel it, which
531
+ no log holds."""
532
+
533
+ import re as _re
534
+ _ID = _re.compile(r"/queries/[^/\s\"]+/cancel")
535
+
536
+ def filter(self, record: Any) -> bool:
537
+ if record.args:
538
+ record.args = tuple(self._ID.sub("/queries/<id>/cancel", a) if isinstance(a, str) else a
539
+ for a in record.args)
540
+ if isinstance(record.msg, str):
541
+ record.msg = self._ID.sub("/queries/<id>/cancel", record.msg)
542
+ return True
543
+
544
+
545
+ def release(engines: EngineSource, engine: Any) -> None:
546
+ """Tell an engine source that a request on `engine` has ended, so an
547
+ engine running a request is not closed as idle (`DatabricksUsers`). A source with no `release` keeps nothing to free."""
548
+ let_go = getattr(engines, "release", None)
549
+ if callable(let_go):
550
+ let_go(engine)
551
+
552
+
553
+ class _ReleaseOnce:
554
+ """`release(engines, engine)`, the first time it is called only."""
555
+
556
+ def __init__(self, engines: EngineSource, engine: Any, then: Optional[Callable[[], None]] = None):
557
+ import threading
558
+ self.engines, self.engine, self.then = engines, engine, then
559
+ self._lock, self._done = threading.Lock(), False
560
+
561
+ def __call__(self) -> None:
562
+ with self._lock:
563
+ if self._done:
564
+ return
565
+ self._done = True
566
+ try:
567
+ release(self.engines, self.engine)
568
+ finally:
569
+ if self.then is not None:
570
+ self.then()
571
+
572
+
573
+ def _released_after(body: Iterator[str], once: _ReleaseOnce) -> Iterator[str]:
574
+ """A streamed answer that releases its engine when it ends, cut or not
575
+ (as soon as the last row is written, before the response closes)."""
576
+ try:
577
+ yield from body
578
+ finally:
579
+ once()
580
+
581
+
582
+ def _ReleasingStream(once: _ReleaseOnce, body: Iterator[str], **kw: Any) -> Any:
583
+ """A StreamingResponse that releases its engine when the response ends,
584
+ whatever ends it. A client gone before the body is first read (Starlette
585
+ cancels the stream on disconnect, under ASGI 2.3 before it starts) never
586
+ runs the body's `finally`, and its engine would stay busy for good: never
587
+ idle, never closed after its credential ends, and holding a slot of
588
+ `--max-user-engines` (the re-check of dc959503)."""
589
+ from starlette.responses import StreamingResponse
590
+
591
+ class Releasing(StreamingResponse):
592
+ async def __call__(self, scope: Any, receive: Any, send: Any) -> None:
593
+ try:
594
+ await super().__call__(scope, receive, send)
595
+ finally:
596
+ close = getattr(self.body_iterator, "aclose", None)
597
+ try:
598
+ if close is not None:
599
+ await close()
600
+ except Exception: # noqa: BLE001 - closing a stream already cut
601
+ pass
602
+ # Off the event loop: a retired engine's connection is closed here.
603
+ import anyio
604
+ await anyio.to_thread.run_sync(once)
605
+
606
+ return Releasing(body, **kw)
607
+
608
+
609
+ def protected_resource_metadata(options: Options) -> dict:
610
+ """/mcp's OAuth 2.0 Protected Resource Metadata (RFC 9728 2), which the
611
+ MCP authorization specification has a client read to find where to
612
+ sign its user in: the resource and its authorization server, the
613
+ identity provider. The SDK's model (`mcp.shared.auth`) checks it; the
614
+ URLs are written as given, since the model's URL type adds a `/` to a
615
+ bare host, and a client compares an issuer as a string (RFC 8414 3.3)."""
616
+ from mcp.shared.auth import ProtectedResourceMetadata
617
+ document = {"resource": f"{options.public_base()}/mcp",
618
+ "authorization_servers": [options.authorization_server],
619
+ "bearer_methods_supported": ["header"],
620
+ "resource_name": "ProGraph MCP server"}
621
+ ProtectedResourceMetadata(**document)
622
+ return document
623
+
624
+
625
+ MCP_TOKEN_HANDLING = ("MCP authorization, Token Handling (specification revision 2026-07-28): "
626
+ "an MCP server accepts only tokens issued for it")
627
+
628
+
629
+ def only_providers_tokens(token: str, workspace_host: str, issuer: str) -> None:
630
+ """With an identity provider configured (`--idp-issuer`), `/mcp` takes
631
+ only the provider's tokens, which Databricks' federation exchange checks
632
+ for their audience; a Databricks workspace token (a personal access
633
+ token, or a JWT the workspace issued) was not issued for this server,
634
+ and passing it on to the warehouse is the token passthrough the MCP
635
+ authorization specification forbids (decided 2026-11-05: "we should
636
+ follow the standard!"). /sparql, which no MCP rule covers, takes both."""
637
+ from prograph.endpoint.credentials import needs_exchange
638
+ if not needs_exchange(token, workspace_host):
639
+ said = (f"this MCP server accepts only tokens from its identity provider ({issuer}), "
640
+ f"not a Databricks workspace token ({MCP_TOKEN_HANDLING})")
641
+ raise ProtocolError(401, said, challenge=f'error="invalid_token", error_description="{said}"')
642
+
643
+
644
+ def _user_guard(asgi: Any, engines: EngineSource, metadata_url: Optional[str],
645
+ issuer: Optional[str] = None, path: str = "/mcp") -> Any:
646
+ """`asgi` behind each user's own credential (`--per-user`): the
647
+ request's engine is found, or opened, before the MCP server reads it,
648
+ so a request with no credential, or one the workspace refuses, is an
649
+ HTTP 401 whose `WWW-Authenticate` names the resource metadata (the
650
+ MCP authorization specification), not a tool result. The tools then
651
+ find the same engine by the same credential. With `issuer` (an
652
+ identity provider configured), a Databricks workspace token is refused
653
+ there before any engine is looked up (`only_providers_tokens`)."""
654
+ import anyio
655
+
656
+ async def guarded(scope: Any, receive: Any, send: Any) -> None:
657
+ if scope["type"] == "http" and scope.get("path", "").rstrip("/") == path:
658
+ from starlette.requests import Request
659
+ from prograph.endpoint.credentials import bearer
660
+ request = Request(scope)
661
+ try:
662
+ token = bearer(request.headers)
663
+ if issuer and token:
664
+ only_providers_tokens(token, getattr(engines, "hostname", ""), issuer)
665
+ engine = await anyio.to_thread.run_sync(engines, request)
666
+ release(engines, engine)
667
+ except ProtocolError as error:
668
+ _log("sparql_endpoint_refused", status=error.status, reason=error.reason[:300])
669
+ headers = [(b"content-type", b"text/plain; charset=utf-8")]
670
+ headers += [(k.lower().encode(), str(v).encode()) for k, v in error.headers.items()]
671
+ if error.status == 401:
672
+ headers.append((b"www-authenticate", error.www_authenticate(metadata_url).encode()))
673
+ await send({"type": "http.response.start", "status": error.status, "headers": headers})
674
+ await send({"type": "http.response.body", "body": (error.reason + "\n").encode()})
675
+ return
676
+ await asgi(scope, receive, send)
677
+
678
+ return guarded
679
+
680
+
681
+ def _own_methods(app: Any, asgi: Any) -> Any:
682
+ """`asgi` for every path but the application's own: a method its route
683
+ does not take (`OPTIONS /sparql`, `POST /healthz`) is a 405 with
684
+ `Allow`, as before the MCP app was mounted at /, not the mount's 401 or
685
+ 404."""
686
+ own: dict = {}
687
+ for route in app.routes:
688
+ if getattr(route, "methods", None):
689
+ own.setdefault(route.path, set()).update(route.methods)
690
+
691
+ async def routed(scope: Any, receive: Any, send: Any) -> None:
692
+ if scope["type"] == "http" and scope.get("path") in own:
693
+ allow = ", ".join(sorted(own[scope["path"]]))
694
+ await send({"type": "http.response.start", "status": 405,
695
+ "headers": [(b"allow", allow.encode()),
696
+ (b"content-type", b"text/plain; charset=utf-8")]})
697
+ await send({"type": "http.response.body", "body": b"method not allowed\n"})
698
+ return
699
+ await asgi(scope, receive, send)
700
+
701
+ return routed
702
+
703
+
704
+ def bearer_guard(asgi: Any, token: Optional[str]) -> Any:
705
+ """`asgi` behind the server's bearer token: 401 without it, as at
706
+ /sparql. No token, no guard."""
707
+ if token is None:
708
+ return asgi
709
+ import hmac
710
+
711
+ async def guarded(scope: Any, receive: Any, send: Any) -> None:
712
+ if scope["type"] == "http":
713
+ given = dict(scope.get("headers") or []).get(b"authorization", b"")
714
+ if not hmac.compare_digest(given, f"Bearer {token}".encode()):
715
+ await send({"type": "http.response.start", "status": 401,
716
+ "headers": [(b"content-type", b"text/plain; charset=utf-8"),
717
+ (b"www-authenticate", b"Bearer")]})
718
+ await send({"type": "http.response.body", "body": b"a bearer token is required\n"})
719
+ return
720
+ await asgi(scope, receive, send)
721
+
722
+ return guarded