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.
- prograph/__init__.py +36 -0
- prograph/__main__.py +5 -0
- prograph/_version.py +375 -0
- prograph/cli/__init__.py +1 -0
- prograph/cli/_iri_utils.py +124 -0
- prograph/cli/emit_genie_space.py +107 -0
- prograph/cli/generate_views.py +140 -0
- prograph/cli/main.py +420 -0
- prograph/cli/schema_inferrer.py +746 -0
- prograph/cli/ttl_loader.py +289 -0
- prograph/cli/upload_genie_space.py +84 -0
- prograph/config/__init__.py +27 -0
- prograph/config/yaml_config.py +848 -0
- prograph/demos/__init__.py +14 -0
- prograph/demos/turbofan/README.md +74 -0
- prograph/demos/turbofan/SCENARIO.md +209 -0
- prograph/demos/turbofan/__init__.py +75 -0
- prograph/demos/turbofan/create_tables.sql +206 -0
- prograph/demos/turbofan/data/engine-instances.ttl +1123 -0
- prograph/demos/turbofan/data/sensor-timeseries.csv +90 -0
- prograph/demos/turbofan/demo.py +162 -0
- prograph/demos/turbofan/genie_qa_notebook.py +434 -0
- prograph/demos/turbofan/graph.yaml +1098 -0
- prograph/demos/turbofan/instance_graph_demo.py +32 -0
- prograph/demos/turbofan/load.py +223 -0
- prograph/demos/turbofan/mapping.r2rml.ttl +991 -0
- prograph/demos/turbofan/ontology/engine-maintenance.ttl +606 -0
- prograph/demos/turbofan/payload-shapes.ttl +33 -0
- prograph/demos/turbofan/queries/example-queries.sparql +215 -0
- prograph/demos/turbofan/shapes.ttl +75 -0
- prograph/demos/turbofan/tables.py +106 -0
- prograph/demos/turbofan/turbofan_schema.py +393 -0
- prograph/demos/turbofan/validation_demo.py +153 -0
- prograph/describe.py +231 -0
- prograph/endpoint/__init__.py +12 -0
- prograph/endpoint/app.py +722 -0
- prograph/endpoint/cli.py +280 -0
- prograph/endpoint/credentials.py +240 -0
- prograph/endpoint/engines.py +418 -0
- prograph/endpoint/negotiate.py +101 -0
- prograph/endpoint/results.py +181 -0
- prograph/endpoint/service.py +31 -0
- prograph/engine.py +2718 -0
- prograph/execution.py +455 -0
- prograph/executors/__init__.py +6 -0
- prograph/executors/base.py +11 -0
- prograph/executors/databricks_sql_executor.py +51 -0
- prograph/executors/duckdb_executor.py +24 -0
- prograph/executors/mysql_executor.py +20 -0
- prograph/executors/oracle_executor.py +24 -0
- prograph/executors/pandas_executor.py +72 -0
- prograph/executors/postgresql_executor.py +35 -0
- prograph/executors/spark_executor.py +88 -0
- prograph/executors/sqlserver_executor.py +35 -0
- prograph/extras/__init__.py +1 -0
- prograph/extras/graphql/__init__.py +33 -0
- prograph/extras/graphql/execute.py +25 -0
- prograph/extras/graphql/schema.py +314 -0
- prograph/extras/instance_graph.py +559 -0
- prograph/genie/__init__.py +83 -0
- prograph/genie/databricks_uploader.py +306 -0
- prograph/genie/deploy.py +393 -0
- prograph/genie/formats.py +414 -0
- prograph/genie/instruction_generator.py +375 -0
- prograph/genie/sample_query_generator.py +256 -0
- prograph/genie/shacl_views.py +318 -0
- prograph/genie/space_emitter.py +329 -0
- prograph/genie/view_generator.py +628 -0
- prograph/genie/view_writer.py +172 -0
- prograph/graph/__init__.py +1 -0
- prograph/graph/ansi_session.py +348 -0
- prograph/graph/databricks_sql_graph.py +300 -0
- prograph/graph/drivers.py +143 -0
- prograph/graph/duckdb_graph.py +68 -0
- prograph/graph/mysql_graph.py +38 -0
- prograph/graph/oracle_graph.py +285 -0
- prograph/graph/pandas_graph.py +343 -0
- prograph/graph/postgresql_graph.py +644 -0
- prograph/graph/spark_graph.py +556 -0
- prograph/graph/sql_graph.py +83 -0
- prograph/graph/sqlserver_graph.py +72 -0
- prograph/hints.py +95 -0
- prograph/logging.py +550 -0
- prograph/mcp/__init__.py +29 -0
- prograph/mcp/__main__.py +180 -0
- prograph/mcp/bootstrap.py +98 -0
- prograph/mcp/server.py +601 -0
- prograph/mcp/sparql.py +397 -0
- prograph/mcp/tools.py +504 -0
- prograph/nlp/__init__.py +79 -0
- prograph/nlp/client.py +305 -0
- prograph/nlp/databricks_tools.py +369 -0
- prograph/nlp/graph_context.py +313 -0
- prograph/nlp/interface.py +652 -0
- prograph/nlp/prompts/__init__.py +19 -0
- prograph/nlp/prompts/examples.py +258 -0
- prograph/nlp/prompts/system.py +239 -0
- prograph/nlp/providers/__init__.py +14 -0
- prograph/nlp/providers/anthropic.py +274 -0
- prograph/nlp/providers/databricks.py +312 -0
- prograph/nlp/providers/openai.py +203 -0
- prograph/nlp/schema_context.py +78 -0
- prograph/ontology/__init__.py +53 -0
- prograph/ontology/alignment.py +542 -0
- prograph/ontology/hierarchy.py +310 -0
- prograph/ontology/imports.py +587 -0
- prograph/ontology/layer.py +991 -0
- prograph/ontology/skos.py +61 -0
- prograph/owl/__init__.py +27 -0
- prograph/owl/defined_classes.py +323 -0
- prograph/parameters.py +242 -0
- prograph/parser/__init__.py +1 -0
- prograph/parser/cypher/CypherLexer.py +836 -0
- prograph/parser/cypher/CypherListener.py +966 -0
- prograph/parser/cypher/CypherParser.py +10854 -0
- prograph/parser/cypher/CypherVisitor.py +543 -0
- prograph/parser/cypher/__init__.py +1 -0
- prograph/parser/sparql/SparqlLexer.py +801 -0
- prograph/parser/sparql/SparqlParser.py +10146 -0
- prograph/parser/sparql/SparqlParserListener.py +1056 -0
- prograph/parser/sparql/SparqlParserVisitor.py +593 -0
- prograph/parser/sparql/__init__.py +8 -0
- prograph/plan/__init__.py +3 -0
- prograph/plan/ir/__init__.py +1 -0
- prograph/plan/ir/casts.py +338 -0
- prograph/plan/ir/consistency.py +397 -0
- prograph/plan/ir/construct.py +90 -0
- prograph/plan/ir/cost.py +234 -0
- prograph/plan/ir/cypher_answer.py +1081 -0
- prograph/plan/ir/cypher_apoc.py +717 -0
- prograph/plan/ir/cypher_apoc_convert.py +505 -0
- prograph/plan/ir/cypher_apoc_date.py +845 -0
- prograph/plan/ir/cypher_apoc_map.py +496 -0
- prograph/plan/ir/cypher_apoc_meta.py +384 -0
- prograph/plan/ir/cypher_apoc_path.py +597 -0
- prograph/plan/ir/cypher_apoc_procedures.py +163 -0
- prograph/plan/ir/cypher_apoc_text.py +785 -0
- prograph/plan/ir/cypher_front.py +5474 -0
- prograph/plan/ir/cypher_functions.py +565 -0
- prograph/plan/ir/cypher_lists.py +935 -0
- prograph/plan/ir/cypher_maps.py +370 -0
- prograph/plan/ir/cypher_mixed.py +604 -0
- prograph/plan/ir/cypher_ontology.py +226 -0
- prograph/plan/ir/cypher_procedures.py +191 -0
- prograph/plan/ir/cypher_runtime_errors.py +107 -0
- prograph/plan/ir/cypher_temporal.py +1357 -0
- prograph/plan/ir/cypher_temporal_arith.py +339 -0
- prograph/plan/ir/cypher_values.py +546 -0
- prograph/plan/ir/cypher_write.py +612 -0
- prograph/plan/ir/dataset.py +643 -0
- prograph/plan/ir/dates.py +102 -0
- prograph/plan/ir/entry.py +992 -0
- prograph/plan/ir/expr.py +260 -0
- prograph/plan/ir/facts.py +1171 -0
- prograph/plan/ir/fresh.py +291 -0
- prograph/plan/ir/freshness.py +625 -0
- prograph/plan/ir/identity.py +797 -0
- prograph/plan/ir/java_datetime.py +265 -0
- prograph/plan/ir/java_regex.py +391 -0
- prograph/plan/ir/join_order.py +39 -0
- prograph/plan/ir/key_checks.py +433 -0
- prograph/plan/ir/keys.py +454 -0
- prograph/plan/ir/lower.py +5323 -0
- prograph/plan/ir/ops.py +619 -0
- prograph/plan/ir/owl_rl.py +1119 -0
- prograph/plan/ir/owl_rl_rules.py +725 -0
- prograph/plan/ir/profiles.py +694 -0
- prograph/plan/ir/ql.py +987 -0
- prograph/plan/ir/rdfs.py +342 -0
- prograph/plan/ir/rewrite.py +1782 -0
- prograph/plan/ir/saturate.py +339 -0
- prograph/plan/ir/semantics.py +103 -0
- prograph/plan/ir/slot.py +509 -0
- prograph/plan/ir/sparql_front.py +3418 -0
- prograph/plan/ir/strings.py +534 -0
- prograph/plan/ir/term_functions.py +274 -0
- prograph/plan/ir/terms.py +84 -0
- prograph/plan/ir/xpath_regex.py +264 -0
- prograph/plan/run_record.py +65 -0
- prograph/plan/sql/__init__.py +21 -0
- prograph/plan/sql/dialect.py +3726 -0
- prograph/plan/sql/mysql_serializer.py +103 -0
- prograph/plan/sql/names.py +65 -0
- prograph/plan/sql/oracle_serializer.py +306 -0
- prograph/plan/sql/pg_serializer.py +501 -0
- prograph/plan/sql/rel_algebra.py +781 -0
- prograph/plan/sql/sql_serializer.py +1419 -0
- prograph/plan/sql/sqlserver_serializer.py +603 -0
- prograph/provenance.py +222 -0
- prograph/r2rml/__init__.py +48 -0
- prograph/r2rml/catalog.py +259 -0
- prograph/r2rml/compile.py +372 -0
- prograph/r2rml/direct.py +140 -0
- prograph/r2rml/export.py +495 -0
- prograph/r2rml/model.py +180 -0
- prograph/r2rml/parser.py +546 -0
- prograph/r2rml/schema.py +120 -0
- prograph/read_only.py +122 -0
- prograph/results.py +157 -0
- prograph/rules/__init__.py +168 -0
- prograph/rules/__main__.py +32 -0
- prograph/schema/__init__.py +60 -0
- prograph/schema/change_set.py +50 -0
- prograph/schema/collations.py +198 -0
- prograph/schema/compile_schema.py +388 -0
- prograph/schema/context.py +845 -0
- prograph/schema/examples.py +234 -0
- prograph/schema/iri.py +817 -0
- prograph/schema/literals.py +94 -0
- prograph/schema/lpg_view.py +617 -0
- prograph/schema/mapping.py +1803 -0
- prograph/schema/maps_schema.py +40 -0
- prograph/schema/naming.py +77 -0
- prograph/schema/query_sources.py +59 -0
- prograph/schema/rows.py +215 -0
- prograph/schema/source_map.py +1103 -0
- prograph/schema/store_view.py +459 -0
- prograph/schema/types.py +569 -0
- prograph/schema/xsd.py +569 -0
- prograph/shacl/__init__.py +30 -0
- prograph/shacl/dqv.py +58 -0
- prograph/shacl/generate.py +255 -0
- prograph/shacl/report.py +138 -0
- prograph/shacl/validator.py +164 -0
- prograph/store.py +1737 -0
- prograph/utils/__init__.py +6 -0
- prograph/utils/exceptions.py +308 -0
- prograph/utils/helpers.py +126 -0
- prograph/warnings.py +46 -0
- prograph/writes.py +369 -0
- prograph-1.3.3.dist-info/METADATA +281 -0
- prograph-1.3.3.dist-info/RECORD +237 -0
- prograph-1.3.3.dist-info/WHEEL +5 -0
- prograph-1.3.3.dist-info/entry_points.txt +3 -0
- prograph-1.3.3.dist-info/licenses/LICENSE +201 -0
- prograph-1.3.3.dist-info/licenses/NOTICE +10 -0
- prograph-1.3.3.dist-info/top_level.txt +1 -0
prograph/endpoint/app.py
ADDED
|
@@ -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)}&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)}' <this address>/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
|