clue-python-sdk-core 0.0.1__py3-none-any.whl

clue_python_sdk_core/http_extraction.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping, Sequence
+from urllib.parse import parse_qs, urlsplit
+
+from .privacy import JsonValue
+
+NUMBER_SEGMENT = re.compile(r"^\d+$")
+UUID_SEGMENT = re.compile(
+	r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
+)
+HEX_SEGMENT = re.compile(r"^[0-9a-fA-F]{16,}$")
+
+
+def _to_json_value(value: object) -> JsonValue:
+	if value is None:
+		return None
+	if isinstance(value, bool):
+		return value
+	if isinstance(value, (int, float)):
+		return value
+	if isinstance(value, str):
+		return value
+	if isinstance(value, bytes):
+		text = value.decode("utf-8", errors="replace").strip()
+		if text.startswith("{") or text.startswith("["):
+			try:
+				return json.loads(text)
+			except json.JSONDecodeError:
+				return text
+		return text
+	if isinstance(value, Mapping):
+		return {str(key): _to_json_value(child) for key, child in value.items()}
+	if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+		return [_to_json_value(child) for child in value]
+	return str(value)
+
+
+def _normalize_headers(headers: object) -> dict[str, JsonValue]:
+	if isinstance(headers, Mapping):
+		return {str(key).lower(): _to_json_value(value) for key, value in headers.items()}
+	if hasattr(headers, "items"):
+		items = getattr(headers, "items")
+		if callable(items):
+			return {
+				str(key).lower(): _to_json_value(value)
+				for key, value in items()
+			}
+	return {}
+
+
+def _extract_request_headers(request: object) -> dict[str, JsonValue]:
+	headers = getattr(request, "headers", None)
+	normalized = _normalize_headers(headers)
+	if normalized:
+		return normalized
+
+	meta = getattr(request, "META", None)
+	if isinstance(meta, Mapping):
+		out: dict[str, JsonValue] = {}
+		for key, value in meta.items():
+			key_text = str(key)
+			if key_text.startswith("HTTP_"):
+				header_name = key_text[5:].replace("_", "-").lower()
+				out[header_name] = _to_json_value(value)
+			elif key_text in {"CONTENT_TYPE", "CONTENT_LENGTH"}:
+				out[key_text.replace("_", "-").lower()] = _to_json_value(value)
+		return out
+
+	return {}
+
+
+def _extract_response_headers(response: object) -> dict[str, JsonValue]:
+	headers = getattr(response, "headers", None)
+	return _normalize_headers(headers)
+
+
+def _extract_query(raw_query: object) -> dict[str, JsonValue]:
+	if raw_query is None:
+		return {}
+	if isinstance(raw_query, Mapping):
+		return {str(key): _to_json_value(value) for key, value in raw_query.items()}
+	if hasattr(raw_query, "lists"):
+		lists_method = getattr(raw_query, "lists")
+		if callable(lists_method):
+			out: dict[str, JsonValue] = {}
+			for key, values in lists_method():
+				out[str(key)] = [_to_json_value(value) for value in values]
+			return out
+	return {}
+
+
+def _request_body(request: object) -> JsonValue | None:
+	for attr in ("body", "data", "json_body"):
+		if hasattr(request, attr):
+			return _to_json_value(getattr(request, attr))
+	return None
+
+
+def _response_body(response: object) -> JsonValue | None:
+	for attr in ("content", "body", "data"):
+		if hasattr(response, attr):
+			return _to_json_value(getattr(response, attr))
+	return None
+
+
+def _safe_urlsplit(raw_url: str) -> tuple[str, str, str, dict[str, JsonValue]]:
+	try:
+		parsed = urlsplit(raw_url)
+		path = parsed.path or "/"
+		host = "" if "%" in (parsed.netloc or "") else (parsed.netloc or "")
+		query_map = {
+			key: values[0] if len(values) == 1 else values
+			for key, values in parse_qs(parsed.query, keep_blank_values=True).items()
+		}
+		return parsed.scheme or "", host, path, {
+			key: _to_json_value(value) for key, value in query_map.items()
+		}
+	except ValueError:
+		return "", "", "/", {}
+
+
+def to_path_template(path: str) -> str:
+	if not path:
+		return "/"
+
+	segments = [segment for segment in path.split("/") if segment]
+	if not segments:
+		return "/"
+
+	templated: list[str] = []
+	for segment in segments:
+		if UUID_SEGMENT.match(segment):
+			templated.append(":uuid")
+			continue
+		if NUMBER_SEGMENT.match(segment):
+			templated.append(":id")
+			continue
+		if HEX_SEGMENT.match(segment):
+			templated.append(":hex")
+			continue
+		templated.append(segment)
+
+	return "/" + "/".join(templated)

clue_python_sdk_core/orm.py

@@ -0,0 +1,534 @@
+from __future__ import annotations
+
+import re
+import time
+from collections.abc import Iterable, Mapping, Sequence
+
+from .adapters import (
+	JsonValue,
+	build_repository_mutation_event,
+	build_state_transition_event,
+	build_summary_event,
+)
+from .contracts import (
+	BACKEND_STATUS_FINISHED,
+	BACKEND_STATUS_STARTED,
+	REPOSITORY_MUTATION_SUMMARY_EVENT,
+	SDK_COLLECTION_MODE_STANDARD,
+)
+from .otel_bridge import annotate_current_otel_span, resolve_current_otel_span_context
+from .runtime import add_event, get_current_client, get_current_context, load_settings
+
+_sqlalchemy_instrumented = False
+_django_orm_instrumented = False
+
+
+def _normalize_dot_case(value: object | None, fallback: str) -> str:
+	text = str(value or fallback).strip()
+	if not text:
+		text = fallback
+	text = re.sub(r"([a-z0-9])([A-Z])", r"\1.\2", text)
+	text = re.sub(r"[^a-zA-Z0-9]+", ".", text).strip(".").lower()
+	text = re.sub(r"\.{2,}", ".", text)
+	return text or fallback
+
+
+def _string_sequence(values: Iterable[object] | None) -> tuple[str, ...]:
+	if values is None:
+		return ()
+	return tuple(
+		dict.fromkeys(str(value).strip() for value in values if str(value).strip())
+	)
+
+
+def _record_summary_metric(client: object, count: int = 1) -> None:
+	record = getattr(client, "record_events_summarized", None)
+	if callable(record):
+		record(count)
+
+
+def _emit_repository_mutation_pair(
+	*,
+	mutation_kind: str,
+	repository_name: str,
+	changed_fields_schema: Sequence[str] = (),
+	entity_id: object | None = None,
+	timer: object = time.perf_counter,
+) -> bool:
+	client = get_current_client()
+	context = get_current_context()
+	if client is None or context is None:
+		return False
+
+	normalized_repository_name = _normalize_dot_case(repository_name, "repository")
+	mutation_key = _normalize_dot_case(
+		f"{normalized_repository_name}.{mutation_kind}",
+		f"repository.{mutation_kind}",
+	)
+	settings = load_settings()
+	if settings.sdk_collection_mode == SDK_COLLECTION_MODE_STANDARD:
+		summary = build_summary_event(
+			context=context,
+			event_name=REPOSITORY_MUTATION_SUMMARY_EVENT,
+			collector_name="orm_write",
+			aggregation_kind="request",
+			summary_window_ms=0,
+			summary_count=1,
+			budget_window_ms=60_000,
+			rate_limit_key=f"repository:{normalized_repository_name}:{mutation_kind}",
+			properties={
+				"mutation_key": mutation_key,
+				"mutation_kind": mutation_kind,
+				"repository_name": normalized_repository_name,
+				"changed_fields_schema": list(changed_fields_schema),
+			},
+			metrics={
+				"normal_success_count": 1,
+			},
+			denied_keys=settings.denied_keys,
+		)
+		added = add_event(summary)
+		if added:
+			_record_summary_metric(client)
+		return added
+
+	started_at = timer()
+	otel_span = resolve_current_otel_span_context("CLIENT")
+	span_id = otel_span["span_id"] if otel_span is not None and otel_span.get("span_id") else None
+	parent_span_id = (
+		otel_span.get("parent_span_id") or None if otel_span is not None else None
+	)
+	annotate_current_otel_span(
+		{
+			"clue.flow.kind": "repository_mutation",
+			"clue.mutation.key": mutation_key,
+			"clue.mutation.kind": mutation_kind,
+			"clue.repository.name": normalized_repository_name,
+			"clue.changed_fields_schema": list(changed_fields_schema),
+		},
+		expected_kind="CLIENT",
+	)
+	started = build_repository_mutation_event(
+		context=context,
+		status=BACKEND_STATUS_STARTED,
+		mutation_key=mutation_key,
+		mutation_kind=mutation_kind,
+		repository_name=normalized_repository_name,
+		changed_fields_schema=changed_fields_schema,
+		entity_id=entity_id,
+		span_id=span_id,
+		parent_span_id=parent_span_id,
+	)
+	finished = build_repository_mutation_event(
+		context=context,
+		status=BACKEND_STATUS_FINISHED,
+		mutation_key=mutation_key,
+		mutation_kind=mutation_kind,
+		repository_name=normalized_repository_name,
+		changed_fields_schema=changed_fields_schema,
+		entity_id=entity_id,
+		duration_ms=max(0, int((timer() - started_at) * 1000)),
+		span_id=span_id,
+		parent_span_id=parent_span_id,
+	)
+
+	return add_event(started) and add_event(finished)
+
+
+def _configured_state_fields() -> tuple[str, ...]:
+	settings = load_settings()
+	return tuple(
+		dict.fromkeys(
+			_normalize_dot_case(field, "")
+			for field in settings.state_fields
+			if str(field).strip()
+		)
+	)
+
+
+def _state_field_matches(field_name: str, configured_fields: Sequence[str]) -> bool:
+	normalized = _normalize_dot_case(field_name, "")
+	snake_name = str(field_name).strip().lower()
+	return normalized in configured_fields or snake_name in configured_fields
+
+
+def _state_value(value: object | None) -> str | None:
+	if value is None or isinstance(value, bool) or isinstance(value, (int, float)):
+		return None
+	text = str(value).strip()
+	return text if text else None
+
+
+def _emit_state_transition_pair(
+	*,
+	repository_name: str,
+	field_name: str,
+	from_value: object | None,
+	to_value: object | None,
+	entity_id: object | None = None,
+	timer: object = time.perf_counter,
+) -> bool:
+	client = get_current_client()
+	context = get_current_context()
+	from_state = _state_value(from_value)
+	to_state = _state_value(to_value)
+	if client is None or context is None or from_state == to_state or to_state is None:
+		return False
+
+	normalized_repository_name = _normalize_dot_case(repository_name, "repository")
+	transition_axis = _normalize_dot_case(field_name, "state")
+	transition_key = _normalize_dot_case(
+		f"{normalized_repository_name}.{transition_axis}",
+		"repository.state",
+	)
+	started_at = timer()
+	otel_span = resolve_current_otel_span_context("INTERNAL")
+	span_id = otel_span["span_id"] if otel_span is not None and otel_span.get("span_id") else None
+	parent_span_id = (
+		otel_span.get("parent_span_id") or None if otel_span is not None else None
+	)
+	annotate_current_otel_span(
+		{
+			"clue.flow.kind": "state_transition",
+			"clue.transition.key": transition_key,
+			"clue.transition.from_state": from_state or "unknown",
+			"clue.transition.to_state": to_state,
+			"clue.transition.axis": transition_axis,
+		},
+		expected_kind="INTERNAL",
+	)
+	started = build_state_transition_event(
+		context=context,
+		status=BACKEND_STATUS_STARTED,
+		transition_key=transition_key,
+		from_state=from_state or "unknown",
+		to_state=to_state,
+		transition_axis=transition_axis,
+		entity_id=entity_id,
+		span_id=span_id,
+		parent_span_id=parent_span_id,
+	)
+	finished = build_state_transition_event(
+		context=context,
+		status=BACKEND_STATUS_FINISHED,
+		transition_key=transition_key,
+		from_state=from_state or "unknown",
+		to_state=to_state,
+		transition_axis=transition_axis,
+		entity_id=entity_id,
+		duration_ms=max(0, int((timer() - started_at) * 1000)),
+		span_id=span_id,
+		parent_span_id=parent_span_id,
+	)
+
+	return add_event(started) and add_event(finished)
+
+
+def _sqlalchemy_repository_name(mapper: object, target: object) -> str:
+	local_table = getattr(mapper, "local_table", None)
+	table_name = getattr(local_table, "name", None)
+	if table_name:
+		return str(table_name)
+	return target.__class__.__name__
+
+
+def _sqlalchemy_entity_id(mapper: object, target: object) -> object | None:
+	primary_keys = getattr(mapper, "primary_key", None)
+	if not primary_keys:
+		return None
+	values: list[object] = []
+	for column in primary_keys:
+		key = getattr(column, "key", None)
+		if key and hasattr(target, str(key)):
+			values.append(getattr(target, str(key)))
+	if len(values) == 1:
+		return values[0]
+	if values:
+		return tuple(values)
+	return None
+
+
+def _sqlalchemy_changed_fields(target: object) -> tuple[str, ...]:
+	try:
+		from sqlalchemy import inspect
+	except ImportError:
+		return ()
+
+	try:
+		state = inspect(target)
+	except Exception:
+		return ()
+
+	fields: list[str] = []
+	for attr in getattr(state, "attrs", ()):
+		key = getattr(attr, "key", None)
+		history = getattr(attr, "history", None)
+		if key and history is not None and callable(getattr(history, "has_changes", None)):
+			if history.has_changes():
+				fields.append(str(key))
+	return tuple(dict.fromkeys(fields))
+
+
+def _sqlalchemy_state_transitions(
+	target: object,
+	configured_fields: Sequence[str],
+) -> tuple[tuple[str, object | None, object | None], ...]:
+	if not configured_fields:
+		return ()
+	try:
+		from sqlalchemy import inspect
+	except ImportError:
+		return ()
+
+	try:
+		state = inspect(target)
+	except Exception:
+		return ()
+
+	transitions: list[tuple[str, object | None, object | None]] = []
+	for attr in getattr(state, "attrs", ()):
+		key = getattr(attr, "key", None)
+		history = getattr(attr, "history", None)
+		if not key or history is None or not _state_field_matches(str(key), configured_fields):
+			continue
+		if not callable(getattr(history, "has_changes", None)) or not history.has_changes():
+			continue
+		deleted = tuple(getattr(history, "deleted", ()) or ())
+		added = tuple(getattr(history, "added", ()) or ())
+		from_value = deleted[0] if deleted else None
+		to_value = added[0] if added else getattr(target, str(key), None)
+		if _state_value(to_value) is None:
+			continue
+		transitions.append((str(key), from_value, to_value))
+	return tuple(transitions)
+
+
+def instrument_sqlalchemy_orm() -> bool:
+	global _sqlalchemy_instrumented
+	if _sqlalchemy_instrumented:
+		return False
+
+	try:
+		from sqlalchemy import event
+		from sqlalchemy.orm import Mapper, Session
+	except ImportError:
+		return False
+
+	def after_insert(mapper: object, _connection: object, target: object) -> None:
+		_emit_repository_mutation_pair(
+			mutation_kind="create",
+			repository_name=_sqlalchemy_repository_name(mapper, target),
+			entity_id=_sqlalchemy_entity_id(mapper, target),
+		)
+
+	def after_update(mapper: object, _connection: object, target: object) -> None:
+		repository_name = _sqlalchemy_repository_name(mapper, target)
+		entity_id = _sqlalchemy_entity_id(mapper, target)
+		_emit_repository_mutation_pair(
+			mutation_kind="update",
+			repository_name=repository_name,
+			changed_fields_schema=_sqlalchemy_changed_fields(target),
+			entity_id=entity_id,
+		)
+		for field_name, from_value, to_value in _sqlalchemy_state_transitions(
+			target,
+			_configured_state_fields(),
+		):
+			_emit_state_transition_pair(
+				repository_name=repository_name,
+				field_name=field_name,
+				from_value=from_value,
+				to_value=to_value,
+				entity_id=entity_id,
+			)
+
+	def after_delete(mapper: object, _connection: object, target: object) -> None:
+		_emit_repository_mutation_pair(
+			mutation_kind="delete",
+			repository_name=_sqlalchemy_repository_name(mapper, target),
+			entity_id=_sqlalchemy_entity_id(mapper, target),
+		)
+
+	def after_bulk_update(update_context: object) -> None:
+		mapper = getattr(update_context, "mapper", None)
+		values = getattr(update_context, "values", None)
+		repository_name = _sqlalchemy_repository_name(mapper, mapper) if mapper else "repository"
+		changed_fields = tuple(str(key) for key in getattr(values, "keys", lambda: ())())
+		_emit_repository_mutation_pair(
+			mutation_kind="bulk_write",
+			repository_name=repository_name,
+			changed_fields_schema=changed_fields,
+		)
+
+	def after_bulk_delete(delete_context: object) -> None:
+		mapper = getattr(delete_context, "mapper", None)
+		repository_name = _sqlalchemy_repository_name(mapper, mapper) if mapper else "repository"
+		_emit_repository_mutation_pair(
+			mutation_kind="bulk_write",
+			repository_name=repository_name,
+		)
+
+	try:
+		event.listen(Mapper, "after_insert", after_insert)
+		event.listen(Mapper, "after_update", after_update)
+		event.listen(Mapper, "after_delete", after_delete)
+		event.listen(Session, "after_bulk_update", after_bulk_update)
+		event.listen(Session, "after_bulk_delete", after_bulk_delete)
+	except Exception:
+		return False
+
+	_sqlalchemy_instrumented = True
+	return True
+
+
+def _django_repository_name(sender: object) -> str:
+	meta = getattr(sender, "_meta", None)
+	db_table = getattr(meta, "db_table", None)
+	model_name = getattr(meta, "model_name", None)
+	return str(db_table or model_name or getattr(sender, "__name__", "model"))
+
+
+def _django_entity_id(instance: object) -> object | None:
+	if hasattr(instance, "pk"):
+		return getattr(instance, "pk")
+	return getattr(instance, "id", None)
+
+
+def _is_framework_django_model(sender: object) -> bool:
+	module_name = str(getattr(sender, "__module__", ""))
+	return module_name.startswith("django.")
+
+
+def _django_state_values(instance: object, fields: Sequence[str]) -> dict[str, object | None]:
+	return {field: getattr(instance, field, None) for field in fields}
+
+
+def _django_state_fields_for_sender(sender: object) -> tuple[str, ...]:
+	configured_fields = _configured_state_fields()
+	if not configured_fields:
+		return ()
+	meta = getattr(sender, "_meta", None)
+	fields = []
+	for field in getattr(meta, "fields", ()) or ():
+		name = getattr(field, "name", None)
+		if name and _state_field_matches(str(name), configured_fields):
+			fields.append(str(name))
+	return tuple(dict.fromkeys(fields))
+
+
+def _django_previous_state_values(
+	sender: object,
+	instance: object,
+	fields: Sequence[str],
+) -> Mapping[str, object | None]:
+	if not fields:
+		return {}
+	primary_key = _django_entity_id(instance)
+	if primary_key is None:
+		return {}
+	manager = getattr(sender, "_default_manager", None)
+	get = getattr(manager, "get", None)
+	if not callable(get):
+		return {}
+	try:
+		previous = get(pk=primary_key)
+	except Exception:
+		return {}
+	return _django_state_values(previous, fields)
+
+
+def instrument_django_orm() -> bool:
+	global _django_orm_instrumented
+	if _django_orm_instrumented:
+		return False
+
+	try:
+		from django.db.models.signals import post_delete, post_save, pre_save
+	except ImportError:
+		return False
+
+	def pre_save_handler(
+		sender: object,
+		instance: object,
+		raw: bool = False,
+		**_kwargs: JsonValue,
+	) -> None:
+		if raw or _is_framework_django_model(sender):
+			return
+		fields = _django_state_fields_for_sender(sender)
+		setattr(
+			instance,
+			"__clue_previous_state_values__",
+			dict(_django_previous_state_values(sender, instance, fields)),
+		)
+
+	def post_save_handler(
+		sender: object,
+		instance: object,
+		created: bool,
+		raw: bool = False,
+		update_fields: object | None = None,
+		**_kwargs: JsonValue,
+	) -> None:
+		if raw or _is_framework_django_model(sender):
+			return
+		repository_name = _django_repository_name(sender)
+		entity_id = _django_entity_id(instance)
+		_emit_repository_mutation_pair(
+			mutation_kind="create" if created else "update",
+			repository_name=repository_name,
+			changed_fields_schema=() if created else _string_sequence(update_fields),
+			entity_id=entity_id,
+		)
+		if created:
+			return
+		configured_state_fields = _django_state_fields_for_sender(sender)
+		update_field_names = _string_sequence(update_fields)
+		previous_values = getattr(instance, "__clue_previous_state_values__", {})
+		if not isinstance(previous_values, Mapping):
+			previous_values = {}
+		for field_name in configured_state_fields:
+			if update_field_names and field_name not in update_field_names:
+				continue
+			_emit_state_transition_pair(
+				repository_name=repository_name,
+				field_name=field_name,
+				from_value=previous_values.get(field_name),
+				to_value=getattr(instance, field_name, None),
+				entity_id=entity_id,
+			)
+
+	def post_delete_handler(
+		sender: object,
+		instance: object,
+		**_kwargs: JsonValue,
+	) -> None:
+		if _is_framework_django_model(sender):
+			return
+		_emit_repository_mutation_pair(
+			mutation_kind="delete",
+			repository_name=_django_repository_name(sender),
+			entity_id=_django_entity_id(instance),
+		)
+
+	try:
+		pre_save.connect(
+			pre_save_handler,
+			dispatch_uid="clue_python_sdk_core.django_orm.pre_save",
+			weak=False,
+		)
+		post_save.connect(
+			post_save_handler,
+			dispatch_uid="clue_python_sdk_core.django_orm.post_save",
+			weak=False,
+		)
+		post_delete.connect(
+			post_delete_handler,
+			dispatch_uid="clue_python_sdk_core.django_orm.post_delete",
+			weak=False,
+		)
+	except Exception:
+		return False
+
+	_django_orm_instrumented = True
+	return True