seqpulse 0.1.0__tar.gz

seqpulse-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Nassir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

seqpulse-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: seqpulse
+Version: 0.1.0
+Summary: SeqPulse SDK for metrics endpoint instrumentation and HMAC validation
+Author: Nassir
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: starlette>=0.36.0
+Dynamic: license-file
+
+# seqpulse (Python SDK)
+
+SeqPulse SDK for:
+
+- HTTP metrics instrumentation
+- metrics endpoint exposure
+- optional HMAC v2 validation on inbound SeqPulse calls
+
+## Install
+
+```bash
+pip install seqpulse
+```
+
+## FastAPI usage
+
+```python
+from fastapi import FastAPI
+from seqpulse import SeqPulse
+
+app = FastAPI()
+
+seqpulse = SeqPulse(
+    api_key="sp_xxx",
+    endpoint="/seqpulse-metrics",
+    hmac_enabled=True,
+    hmac_secret="hmac_xxx",
+)
+
+app.middleware("http")(seqpulse.middleware())
+```
+
+## Returned payload
+
+`GET /seqpulse-metrics` returns:
+
+```json
+{
+  "metrics": {
+    "requests_per_sec": 0.25,
+    "latency_p95": 31.221,
+    "error_rate": 0,
+    "cpu_usage": 0.42,
+    "memory_usage": 0.18
+  }
+}
+```
+
+## Notes
+
+- This SDK does not manage CI/CD trigger/finish workflow.
+- `api_key` is required for config consistency, but not used directly in endpoint responses.
+
+## Local smoke test
+
+```bash
+python scripts/smoke.py
+```

seqpulse-0.1.0/README.md

@@ -0,0 +1,58 @@
+# seqpulse (Python SDK)
+
+SeqPulse SDK for:
+
+- HTTP metrics instrumentation
+- metrics endpoint exposure
+- optional HMAC v2 validation on inbound SeqPulse calls
+
+## Install
+
+```bash
+pip install seqpulse
+```
+
+## FastAPI usage
+
+```python
+from fastapi import FastAPI
+from seqpulse import SeqPulse
+
+app = FastAPI()
+
+seqpulse = SeqPulse(
+    api_key="sp_xxx",
+    endpoint="/seqpulse-metrics",
+    hmac_enabled=True,
+    hmac_secret="hmac_xxx",
+)
+
+app.middleware("http")(seqpulse.middleware())
+```
+
+## Returned payload
+
+`GET /seqpulse-metrics` returns:
+
+```json
+{
+  "metrics": {
+    "requests_per_sec": 0.25,
+    "latency_p95": 31.221,
+    "error_rate": 0,
+    "cpu_usage": 0.42,
+    "memory_usage": 0.18
+  }
+}
+```
+
+## Notes
+
+- This SDK does not manage CI/CD trigger/finish workflow.
+- `api_key` is required for config consistency, but not used directly in endpoint responses.
+
+## Local smoke test
+
+```bash
+python scripts/smoke.py
+```

seqpulse-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "seqpulse"
+version = "0.1.0"
+description = "SeqPulse SDK for metrics endpoint instrumentation and HMAC validation"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+  { name = "Nassir" }
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Framework :: FastAPI",
+  "Topic :: Software Development :: Libraries :: Python Modules"
+]
+dependencies = [
+  "psutil>=5.9.0",
+  "starlette>=0.36.0"
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["seqpulse*"]

seqpulse-0.1.0/seqpulse/__init__.py

@@ -0,0 +1,4 @@
+from .core import SeqPulse
+from .core import SeqPulse as SeqPulseMiddleware
+
+__all__ = ["SeqPulse", "SeqPulseMiddleware"]

seqpulse-0.1.0/seqpulse/core.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import math
+import os
+import secrets
+import time
+from collections import deque
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Callable
+
+try:
+    import psutil
+except ImportError:  # pragma: no cover
+    psutil = None
+from starlette.responses import JSONResponse
+
+
+def _canonicalize_path(path: str) -> str:
+    if not path:
+        return "/"
+    if not path.startswith("/"):
+        path = f"/{path}"
+    if path != "/" and path.endswith("/"):
+        path = path[:-1]
+    return path
+
+
+def _p95(values: list[float]) -> float:
+    if not values:
+        return 0.0
+    sorted_values = sorted(values)
+    index = int(math.floor(0.95 * (len(sorted_values) - 1)))
+    return sorted_values[index]
+
+
+@dataclass
+class _Sample:
+    at_ms: float
+    latency_ms: float
+    is_error: bool
+
+
+class SeqPulse:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        endpoint: str = "/seqpulse-metrics",
+        hmac_enabled: bool = False,
+        hmac_secret: str | None = None,
+        window_seconds: int = 60,
+        max_skew_past_seconds: int = 300,
+        max_skew_future_seconds: int = 30,
+        debug: bool = False,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        if hmac_enabled and not hmac_secret:
+            raise ValueError("hmac_secret is required when hmac_enabled=True")
+        if window_seconds <= 0:
+            raise ValueError("window_seconds must be positive")
+
+        self.api_key = api_key
+        self.endpoint = _canonicalize_path(endpoint)
+        self.hmac_enabled = bool(hmac_enabled)
+        self.hmac_secret = hmac_secret or ""
+        self.window_seconds = int(window_seconds)
+        self.max_skew_past_seconds = int(max_skew_past_seconds)
+        self.max_skew_future_seconds = int(max_skew_future_seconds)
+        self.debug = bool(debug)
+
+        self._samples: deque[_Sample] = deque()
+        self._nonces_seen_at_ms: dict[str, float] = {}
+
+    def _now_ms(self) -> float:
+        return time.time() * 1000.0
+
+    def _cleanup_samples(self) -> None:
+        cutoff = self._now_ms() - self.window_seconds * 1000.0
+        while self._samples and self._samples[0].at_ms < cutoff:
+            self._samples.popleft()
+
+    def _cleanup_nonces(self) -> None:
+        ttl_ms = (self.max_skew_past_seconds + self.max_skew_future_seconds) * 1000.0
+        cutoff = self._now_ms() - ttl_ms
+        stale = [nonce for nonce, seen_ms in self._nonces_seen_at_ms.items() if seen_ms < cutoff]
+        for nonce in stale:
+            del self._nonces_seen_at_ms[nonce]
+
+    def _metrics_snapshot(self) -> dict[str, float]:
+        self._cleanup_samples()
+        samples = list(self._samples)
+        sample_count = len(samples)
+        latencies = [sample.latency_ms for sample in samples]
+        errors = sum(1 for sample in samples if sample.is_error)
+
+        if psutil is not None:
+            cpu = max(0.0, min(psutil.cpu_percent(interval=None) / 100.0, 1.0))
+            mem = max(0.0, min(psutil.virtual_memory().percent / 100.0, 1.0))
+        else:
+            cpu = 0.0
+            mem = 0.0
+
+        return {
+            "requests_per_sec": round(sample_count / self.window_seconds, 3),
+            "latency_p95": round(_p95(latencies), 3),
+            "error_rate": round((errors / sample_count), 6) if sample_count > 0 else 0.0,
+            "cpu_usage": round(cpu, 6),
+            "memory_usage": round(mem, 6),
+        }
+
+    def _build_signature(self, timestamp: str, method: str, path: str, nonce: str) -> str:
+        payload = f"{timestamp}|{method.upper()}|{_canonicalize_path(path)}|{nonce}"
+        digest = hmac.new(self.hmac_secret.encode(), payload.encode(), hashlib.sha256).hexdigest()
+        return f"sha256={digest}"
+
+    def _validate_timestamp(self, ts: str) -> None:
+        sent = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+        now = datetime.now(timezone.utc)
+        delta = (now - sent).total_seconds()
+        if delta > self.max_skew_past_seconds:
+            raise ValueError("Timestamp too old")
+        if delta < -self.max_skew_future_seconds:
+            raise ValueError("Timestamp too far in the future")
+
+    def _validate_hmac_request(self, request: Any) -> tuple[bool, str | None]:
+        if not self.hmac_enabled:
+            return True, None
+
+        timestamp = request.headers.get("X-SeqPulse-Timestamp", "")
+        signature = request.headers.get("X-SeqPulse-Signature", "")
+        nonce = request.headers.get("X-SeqPulse-Nonce", "")
+        version = request.headers.get("X-SeqPulse-Signature-Version", "")
+        method = (request.headers.get("X-SeqPulse-Method") or request.method or "GET").upper()
+        path = _canonicalize_path(
+            request.headers.get("X-SeqPulse-Canonical-Path") or request.url.path or "/"
+        )
+
+        if not timestamp or not signature or not nonce or version != "v2":
+            return False, "Missing or invalid HMAC headers"
+
+        try:
+            self._validate_timestamp(timestamp)
+        except Exception as exc:
+            return False, str(exc)
+
+        self._cleanup_nonces()
+        if nonce in self._nonces_seen_at_ms:
+            return False, "Nonce reuse"
+
+        expected = self._build_signature(timestamp=timestamp, method=method, path=path, nonce=nonce)
+        if not hmac.compare_digest(expected, signature):
+            return False, "Invalid signature"
+
+        self._nonces_seen_at_ms[nonce] = self._now_ms()
+        return True, None
+
+    def middleware(self) -> Callable:
+        async def _middleware(request: Any, call_next: Callable) -> Any:
+            request_path = _canonicalize_path(request.url.path)
+            request_method = (request.method or "GET").upper()
+
+            if request_path == self.endpoint and request_method == "GET":
+                is_valid, reason = self._validate_hmac_request(request)
+                if not is_valid:
+                    return JSONResponse(status_code=401, content={"error": reason or "Unauthorized"})
+                return JSONResponse(content={"metrics": self._metrics_snapshot()})
+
+            started_at = time.perf_counter()
+            response = await call_next(request)
+            latency_ms = (time.perf_counter() - started_at) * 1000.0
+            self._samples.append(
+                _Sample(
+                    at_ms=self._now_ms(),
+                    latency_ms=latency_ms,
+                    is_error=response.status_code >= 500,
+                )
+            )
+            self._cleanup_samples()
+            return response
+
+        return _middleware
+
+    def capture_http_metrics(self) -> Callable:
+        return self.middleware()
+
+    def metrics_handler(self) -> Callable:
+        async def _handler(request: Any) -> JSONResponse:
+            is_valid, reason = self._validate_hmac_request(request)
+            if not is_valid:
+                return JSONResponse(status_code=401, content={"error": reason or "Unauthorized"})
+            return JSONResponse(content={"metrics": self._metrics_snapshot()})
+
+        return _handler
+
+    @staticmethod
+    def generate_nonce() -> str:
+        return secrets.token_urlsafe(16)
+
+
+__all__ = ["SeqPulse"]

seqpulse-0.1.0/seqpulse.egg-info/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: seqpulse
+Version: 0.1.0
+Summary: SeqPulse SDK for metrics endpoint instrumentation and HMAC validation
+Author: Nassir
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: starlette>=0.36.0
+Dynamic: license-file
+
+# seqpulse (Python SDK)
+
+SeqPulse SDK for:
+
+- HTTP metrics instrumentation
+- metrics endpoint exposure
+- optional HMAC v2 validation on inbound SeqPulse calls
+
+## Install
+
+```bash
+pip install seqpulse
+```
+
+## FastAPI usage
+
+```python
+from fastapi import FastAPI
+from seqpulse import SeqPulse
+
+app = FastAPI()
+
+seqpulse = SeqPulse(
+    api_key="sp_xxx",
+    endpoint="/seqpulse-metrics",
+    hmac_enabled=True,
+    hmac_secret="hmac_xxx",
+)
+
+app.middleware("http")(seqpulse.middleware())
+```
+
+## Returned payload
+
+`GET /seqpulse-metrics` returns:
+
+```json
+{
+  "metrics": {
+    "requests_per_sec": 0.25,
+    "latency_p95": 31.221,
+    "error_rate": 0,
+    "cpu_usage": 0.42,
+    "memory_usage": 0.18
+  }
+}
+```
+
+## Notes
+
+- This SDK does not manage CI/CD trigger/finish workflow.
+- `api_key` is required for config consistency, but not used directly in endpoint responses.
+
+## Local smoke test
+
+```bash
+python scripts/smoke.py
+```

seqpulse-0.1.0/seqpulse.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+seqpulse/__init__.py
+seqpulse/core.py
+seqpulse.egg-info/PKG-INFO
+seqpulse.egg-info/SOURCES.txt
+seqpulse.egg-info/dependency_links.txt
+seqpulse.egg-info/requires.txt
+seqpulse.egg-info/top_level.txt

seqpulse-0.1.0/seqpulse.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

seqpulse-0.1.0/seqpulse.egg-info/requires.txt

@@ -0,0 +1,2 @@
+psutil>=5.9.0
+starlette>=0.36.0

seqpulse-0.1.0/seqpulse.egg-info/top_level.txt

@@ -0,0 +1 @@
+seqpulse

seqpulse-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+