krill-core 0.1.2__tar.gz
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.
- krill_core-0.1.2/PKG-INFO +86 -0
- krill_core-0.1.2/README.md +77 -0
- krill_core-0.1.2/pyproject.toml +15 -0
- krill_core-0.1.2/src/krill_core/__init__.py +34 -0
- krill_core-0.1.2/src/krill_core/_errors.py +11 -0
- krill_core-0.1.2/src/krill_core/_http.py +75 -0
- krill_core-0.1.2/src/krill_core/_persistence.py +289 -0
- krill_core-0.1.2/src/krill_core/_recording.py +44 -0
- krill_core-0.1.2/src/krill_core/py.typed +0 -0
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
Metadata-Version: 2.3
|
|
2
|
+
Name: krill-core
|
|
3
|
+
Version: 0.1.2
|
|
4
|
+
Summary: Shared recording contract for the krill toolkit — internal, not for standalone use
|
|
5
|
+
Author: anonymous
|
|
6
|
+
Classifier: Intended Audience :: Developers
|
|
7
|
+
Requires-Python: >=3.10
|
|
8
|
+
Description-Content-Type: text/markdown
|
|
9
|
+
|
|
10
|
+
# krill-core
|
|
11
|
+
|
|
12
|
+
> The krill's shared skeleton — the contract every other package feeds on.
|
|
13
|
+
|
|
14
|
+
Shared recording contract for the krill toolkit: HTTP primitives, the recording model, its persistence, and the error base.
|
|
15
|
+
|
|
16
|
+
## Install
|
|
17
|
+
|
|
18
|
+
An internal shared contract, published only as a dependency of [`krill-fuzzer`](../krill-fuzzer) and [`krill-collector`](../krill-collector) — not intended for standalone use; install one of those instead. Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/). For workspace development, from the root:
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
uv sync # installs all workspace members editable, krill-core included
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Usage
|
|
25
|
+
|
|
26
|
+
Import through a re-exporting package — [`krill-fuzzer`](../krill-fuzzer) here; `krill-collector` re-exports the producer-side names.
|
|
27
|
+
|
|
28
|
+
```python
|
|
29
|
+
from pathlib import Path
|
|
30
|
+
|
|
31
|
+
from krill_fuzzer import load_recording, save_recording
|
|
32
|
+
|
|
33
|
+
recording = load_recording(Path("requests.json")) # -> WorkflowRecording
|
|
34
|
+
save_recording(recording, Path("copy.json"))
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## API
|
|
38
|
+
|
|
39
|
+
Re-exported through `krill_collector` and `krill_fuzzer`.
|
|
40
|
+
|
|
41
|
+
**HTTP primitives** — `krill_core._http`
|
|
42
|
+
|
|
43
|
+
- `HttpMethod` — enum of HTTP verbs.
|
|
44
|
+
- `HttpRequest` — method, URL, headers, body of one request.
|
|
45
|
+
- `HttpResponse` — status, headers, body of one response.
|
|
46
|
+
- `HttpExchange` — one request paired with its response.
|
|
47
|
+
|
|
48
|
+
**Recording model** — `krill_core._recording`
|
|
49
|
+
|
|
50
|
+
- `EventType` — enum of recorded interaction kinds.
|
|
51
|
+
- `RecordedEvent` — one recorded user/workflow event.
|
|
52
|
+
- `WorkflowRecording` — the full recording: exchanges, events, target, timings, optional `extract_as` map.
|
|
53
|
+
- `ExtractAsMap` — extraction bindings carried on a recording.
|
|
54
|
+
|
|
55
|
+
**Persistence** — `krill_core._persistence`
|
|
56
|
+
|
|
57
|
+
- `save_recording(recording: WorkflowRecording, path: Path) -> None` — write a recording to JSON.
|
|
58
|
+
- `load_recording(path: Path) -> WorkflowRecording` — read a recording from JSON.
|
|
59
|
+
|
|
60
|
+
**Errors** — `krill_core._errors`
|
|
61
|
+
|
|
62
|
+
- `KrillError` — base of every error the toolkit raises.
|
|
63
|
+
- `PersistenceError` — a save/load failure; subclass of `KrillError`.
|
|
64
|
+
|
|
65
|
+
## Background
|
|
66
|
+
|
|
67
|
+
Internal foundation package, published only as a shared dependency, not for standalone use — its names are re-exported through [`krill-collector`](../krill-collector) (the producer) and [`krill-fuzzer`](../krill-fuzzer) (the consumer), and consumers import them from there. Its purpose is to keep the recording contract in one place so the collector and the fuzzer agree on the same types without the fuzzer inheriting the collector's browser dependency.
|
|
68
|
+
|
|
69
|
+
## Documentation
|
|
70
|
+
|
|
71
|
+
- [Docs index](docs/index.md) — persistence design and implementation notes.
|
|
72
|
+
|
|
73
|
+
## Citation
|
|
74
|
+
|
|
75
|
+
```bibtex
|
|
76
|
+
@misc{citation_placeholder,
|
|
77
|
+
title = {{TODO: paper title — not yet released}},
|
|
78
|
+
author = {{TODO: authors}},
|
|
79
|
+
year = {{TODO}},
|
|
80
|
+
note = {Paper not yet released. Citation entry will be updated on publication.}
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## License
|
|
85
|
+
|
|
86
|
+
[`GPL-2.0`](../../LICENSE)
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# krill-core
|
|
2
|
+
|
|
3
|
+
> The krill's shared skeleton — the contract every other package feeds on.
|
|
4
|
+
|
|
5
|
+
Shared recording contract for the krill toolkit: HTTP primitives, the recording model, its persistence, and the error base.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
An internal shared contract, published only as a dependency of [`krill-fuzzer`](../krill-fuzzer) and [`krill-collector`](../krill-collector) — not intended for standalone use; install one of those instead. Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/). For workspace development, from the root:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
uv sync # installs all workspace members editable, krill-core included
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Usage
|
|
16
|
+
|
|
17
|
+
Import through a re-exporting package — [`krill-fuzzer`](../krill-fuzzer) here; `krill-collector` re-exports the producer-side names.
|
|
18
|
+
|
|
19
|
+
```python
|
|
20
|
+
from pathlib import Path
|
|
21
|
+
|
|
22
|
+
from krill_fuzzer import load_recording, save_recording
|
|
23
|
+
|
|
24
|
+
recording = load_recording(Path("requests.json")) # -> WorkflowRecording
|
|
25
|
+
save_recording(recording, Path("copy.json"))
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## API
|
|
29
|
+
|
|
30
|
+
Re-exported through `krill_collector` and `krill_fuzzer`.
|
|
31
|
+
|
|
32
|
+
**HTTP primitives** — `krill_core._http`
|
|
33
|
+
|
|
34
|
+
- `HttpMethod` — enum of HTTP verbs.
|
|
35
|
+
- `HttpRequest` — method, URL, headers, body of one request.
|
|
36
|
+
- `HttpResponse` — status, headers, body of one response.
|
|
37
|
+
- `HttpExchange` — one request paired with its response.
|
|
38
|
+
|
|
39
|
+
**Recording model** — `krill_core._recording`
|
|
40
|
+
|
|
41
|
+
- `EventType` — enum of recorded interaction kinds.
|
|
42
|
+
- `RecordedEvent` — one recorded user/workflow event.
|
|
43
|
+
- `WorkflowRecording` — the full recording: exchanges, events, target, timings, optional `extract_as` map.
|
|
44
|
+
- `ExtractAsMap` — extraction bindings carried on a recording.
|
|
45
|
+
|
|
46
|
+
**Persistence** — `krill_core._persistence`
|
|
47
|
+
|
|
48
|
+
- `save_recording(recording: WorkflowRecording, path: Path) -> None` — write a recording to JSON.
|
|
49
|
+
- `load_recording(path: Path) -> WorkflowRecording` — read a recording from JSON.
|
|
50
|
+
|
|
51
|
+
**Errors** — `krill_core._errors`
|
|
52
|
+
|
|
53
|
+
- `KrillError` — base of every error the toolkit raises.
|
|
54
|
+
- `PersistenceError` — a save/load failure; subclass of `KrillError`.
|
|
55
|
+
|
|
56
|
+
## Background
|
|
57
|
+
|
|
58
|
+
Internal foundation package, published only as a shared dependency, not for standalone use — its names are re-exported through [`krill-collector`](../krill-collector) (the producer) and [`krill-fuzzer`](../krill-fuzzer) (the consumer), and consumers import them from there. Its purpose is to keep the recording contract in one place so the collector and the fuzzer agree on the same types without the fuzzer inheriting the collector's browser dependency.
|
|
59
|
+
|
|
60
|
+
## Documentation
|
|
61
|
+
|
|
62
|
+
- [Docs index](docs/index.md) — persistence design and implementation notes.
|
|
63
|
+
|
|
64
|
+
## Citation
|
|
65
|
+
|
|
66
|
+
```bibtex
|
|
67
|
+
@misc{citation_placeholder,
|
|
68
|
+
title = {{TODO: paper title — not yet released}},
|
|
69
|
+
author = {{TODO: authors}},
|
|
70
|
+
year = {{TODO}},
|
|
71
|
+
note = {Paper not yet released. Citation entry will be updated on publication.}
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## License
|
|
76
|
+
|
|
77
|
+
[`GPL-2.0`](../../LICENSE)
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "krill-core"
|
|
3
|
+
version = "0.1.2"
|
|
4
|
+
description = "Shared recording contract for the krill toolkit — internal, not for standalone use"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
authors = [
|
|
7
|
+
{ name = "anonymous" }
|
|
8
|
+
]
|
|
9
|
+
requires-python = ">=3.10"
|
|
10
|
+
classifiers = ["Intended Audience :: Developers"]
|
|
11
|
+
dependencies = []
|
|
12
|
+
|
|
13
|
+
[build-system]
|
|
14
|
+
requires = ["uv_build>=0.11.26,<0.12"]
|
|
15
|
+
build-backend = "uv_build"
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
"""krill-core — shared recording contract for the krill toolkit.
|
|
2
|
+
|
|
3
|
+
Private foundation depended on by krill-collector (producer) and
|
|
4
|
+
krill-fuzzer (consumer): HTTP primitives, the recording data model, its
|
|
5
|
+
JSON persistence, and the KrillError base. Consumers import these names
|
|
6
|
+
through krill_collector or krill_fuzzer, which re-export them.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
from krill_core._errors import KrillError, PersistenceError
|
|
12
|
+
from krill_core._http import HttpExchange, HttpMethod, HttpRequest, HttpResponse
|
|
13
|
+
from krill_core._persistence import load_recording, save_recording
|
|
14
|
+
from krill_core._recording import (
|
|
15
|
+
EventType,
|
|
16
|
+
ExtractAsMap,
|
|
17
|
+
RecordedEvent,
|
|
18
|
+
WorkflowRecording,
|
|
19
|
+
)
|
|
20
|
+
|
|
21
|
+
__all__ = [
|
|
22
|
+
"HttpMethod",
|
|
23
|
+
"HttpRequest",
|
|
24
|
+
"HttpResponse",
|
|
25
|
+
"HttpExchange",
|
|
26
|
+
"EventType",
|
|
27
|
+
"RecordedEvent",
|
|
28
|
+
"WorkflowRecording",
|
|
29
|
+
"ExtractAsMap",
|
|
30
|
+
"save_recording",
|
|
31
|
+
"load_recording",
|
|
32
|
+
"KrillError",
|
|
33
|
+
"PersistenceError",
|
|
34
|
+
]
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
"""KrillError base and the persistence error shared across the toolkit."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class KrillError(Exception):
|
|
7
|
+
"""Base exception for all krill errors."""
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class PersistenceError(KrillError):
|
|
11
|
+
"""Recording serialization or deserialization failure."""
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
"""HTTP primitives — HttpMethod, HttpRequest, HttpResponse, HttpExchange."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from dataclasses import dataclass, field
|
|
6
|
+
from typing import ClassVar
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
@dataclass(frozen=True)
|
|
10
|
+
class HttpMethod:
|
|
11
|
+
"""An HTTP request method — a standard verb or an extension method.
|
|
12
|
+
|
|
13
|
+
A black-box fuzzer records whatever verb the workflow uses, including
|
|
14
|
+
WebDAV and custom extension methods (e.g. ``PROPFIND``) and mutated
|
|
15
|
+
verbs. Construction therefore accepts any non-empty token, normalized
|
|
16
|
+
to upper case, so recorded methods round-trip without loss. The seven
|
|
17
|
+
standard verbs are exposed as class constants (``HttpMethod.GET`` …).
|
|
18
|
+
|
|
19
|
+
Attributes:
|
|
20
|
+
value: The upper-cased method token.
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
value: str
|
|
24
|
+
|
|
25
|
+
GET: ClassVar[HttpMethod]
|
|
26
|
+
POST: ClassVar[HttpMethod]
|
|
27
|
+
PUT: ClassVar[HttpMethod]
|
|
28
|
+
PATCH: ClassVar[HttpMethod]
|
|
29
|
+
DELETE: ClassVar[HttpMethod]
|
|
30
|
+
HEAD: ClassVar[HttpMethod]
|
|
31
|
+
OPTIONS: ClassVar[HttpMethod]
|
|
32
|
+
|
|
33
|
+
def __post_init__(self) -> None:
|
|
34
|
+
normalized = self.value.strip().upper()
|
|
35
|
+
if not normalized:
|
|
36
|
+
raise ValueError("HTTP method must not be empty")
|
|
37
|
+
object.__setattr__(self, "value", normalized)
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
HttpMethod.GET = HttpMethod("GET")
|
|
41
|
+
HttpMethod.POST = HttpMethod("POST")
|
|
42
|
+
HttpMethod.PUT = HttpMethod("PUT")
|
|
43
|
+
HttpMethod.PATCH = HttpMethod("PATCH")
|
|
44
|
+
HttpMethod.DELETE = HttpMethod("DELETE")
|
|
45
|
+
HttpMethod.HEAD = HttpMethod("HEAD")
|
|
46
|
+
HttpMethod.OPTIONS = HttpMethod("OPTIONS")
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
@dataclass(frozen=True)
|
|
50
|
+
class HttpRequest:
|
|
51
|
+
"""A single concrete HTTP request ready for transmission."""
|
|
52
|
+
|
|
53
|
+
method: HttpMethod
|
|
54
|
+
url: str
|
|
55
|
+
headers: dict[str, str] = field(default_factory=dict)
|
|
56
|
+
body: bytes | None = None
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
@dataclass(frozen=True)
|
|
60
|
+
class HttpResponse:
|
|
61
|
+
"""A single HTTP response received from the target server."""
|
|
62
|
+
|
|
63
|
+
status_code: int
|
|
64
|
+
headers: dict[str, str] = field(default_factory=dict)
|
|
65
|
+
body: bytes = b""
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
@dataclass(frozen=True)
|
|
69
|
+
class HttpExchange:
|
|
70
|
+
"""A paired HTTP request and its response, timestamped."""
|
|
71
|
+
|
|
72
|
+
request: HttpRequest
|
|
73
|
+
response: HttpResponse
|
|
74
|
+
timestamp: float
|
|
75
|
+
inject_cookies: dict[str, str] = field(default_factory=dict)
|
|
@@ -0,0 +1,289 @@
|
|
|
1
|
+
"""Persistence boundary — WorkflowRecording <-> JSON file.
|
|
2
|
+
|
|
3
|
+
Single place where recordings cross between in-memory types and the
|
|
4
|
+
filesystem. ``save_recording`` and ``load_recording`` are inverses:
|
|
5
|
+
``load_recording(path)`` after ``save_recording(r, path)`` yields a
|
|
6
|
+
recording equivalent to ``r``.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import base64
|
|
12
|
+
import json
|
|
13
|
+
import re
|
|
14
|
+
from pathlib import Path
|
|
15
|
+
from typing import Any
|
|
16
|
+
|
|
17
|
+
from krill_core._errors import PersistenceError
|
|
18
|
+
from krill_core._http import HttpExchange, HttpMethod, HttpRequest, HttpResponse
|
|
19
|
+
from krill_core._recording import (
|
|
20
|
+
EventType,
|
|
21
|
+
ExtractAsMap,
|
|
22
|
+
RecordedEvent,
|
|
23
|
+
WorkflowRecording,
|
|
24
|
+
)
|
|
25
|
+
|
|
26
|
+
SCHEMA_VERSION = 2
|
|
27
|
+
"""Recording JSON format version. ``load_recording`` rejects versions it does
|
|
28
|
+
not recognize, so a recording written in a newer format fails fast instead of
|
|
29
|
+
being silently mis-parsed by an older reader. A file without the field predates
|
|
30
|
+
versioning and is read as the current format. Version 2 represents a non-text
|
|
31
|
+
body as a ``{"encoding": "base64", "data": ...}`` object so binary bodies
|
|
32
|
+
survive intact."""
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def save_recording(recording: WorkflowRecording, path: Path) -> None:
|
|
36
|
+
"""Serialize a WorkflowRecording to a JSON file.
|
|
37
|
+
|
|
38
|
+
Args:
|
|
39
|
+
path: Destination file path.
|
|
40
|
+
|
|
41
|
+
Raises:
|
|
42
|
+
PersistenceError: If the file cannot be written.
|
|
43
|
+
"""
|
|
44
|
+
try:
|
|
45
|
+
path.write_text(json.dumps(_serialize(recording), indent=2), encoding="utf-8")
|
|
46
|
+
except OSError as exc:
|
|
47
|
+
raise PersistenceError(f"Cannot write recording to {path}: {exc}") from exc
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def load_recording(path: Path) -> WorkflowRecording:
|
|
51
|
+
"""Deserialize a WorkflowRecording from a JSON file.
|
|
52
|
+
|
|
53
|
+
Args:
|
|
54
|
+
path: Path to a JSON file containing a serialized workflow.
|
|
55
|
+
|
|
56
|
+
Returns:
|
|
57
|
+
WorkflowRecording with exchanges, events, and extract_as_map.
|
|
58
|
+
|
|
59
|
+
Raises:
|
|
60
|
+
PersistenceError: If file not found, invalid JSON, or missing fields.
|
|
61
|
+
"""
|
|
62
|
+
if not path.exists():
|
|
63
|
+
raise PersistenceError(f"Workflow file not found: {path}")
|
|
64
|
+
if not path.is_file():
|
|
65
|
+
raise PersistenceError(f"Not a file: {path}")
|
|
66
|
+
|
|
67
|
+
try:
|
|
68
|
+
raw = json.loads(path.read_text(encoding="utf-8"))
|
|
69
|
+
except json.JSONDecodeError as exc:
|
|
70
|
+
raise PersistenceError(f"Invalid JSON in {path}: {exc}") from exc
|
|
71
|
+
|
|
72
|
+
_check_schema_version(raw, path)
|
|
73
|
+
|
|
74
|
+
try:
|
|
75
|
+
return _reconstruct_recording(raw)
|
|
76
|
+
except (KeyError, TypeError, ValueError) as exc:
|
|
77
|
+
raise PersistenceError(f"Missing or invalid fields in {path}: {exc}") from exc
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def _reconstruct_recording(raw: dict[str, Any]) -> WorkflowRecording:
|
|
81
|
+
"""Rebuild a WorkflowRecording from a parsed, version-checked JSON dict."""
|
|
82
|
+
raw_exchanges = raw["exchanges"]
|
|
83
|
+
extract_as_map = _parse_extract_as_map(raw_exchanges)
|
|
84
|
+
placeholders = {name for step in extract_as_map.values() for name in step}
|
|
85
|
+
exchanges = [_reconstruct_exchange(ex, placeholders) for ex in raw_exchanges]
|
|
86
|
+
events = [_reconstruct_event(ev) for ev in raw.get("events", [])]
|
|
87
|
+
return WorkflowRecording(
|
|
88
|
+
exchanges=exchanges,
|
|
89
|
+
events=events,
|
|
90
|
+
target_url=raw["target_url"],
|
|
91
|
+
started_at=raw.get("started_at", 0.0),
|
|
92
|
+
ended_at=raw.get("ended_at", 0.0),
|
|
93
|
+
extract_as_map=extract_as_map or None,
|
|
94
|
+
)
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def _check_schema_version(raw: Any, path: Path) -> None:
|
|
98
|
+
"""Reject a recording whose declared format version is unrecognized."""
|
|
99
|
+
if not isinstance(raw, dict):
|
|
100
|
+
return
|
|
101
|
+
version = raw.get("schema_version")
|
|
102
|
+
if version is not None and version != SCHEMA_VERSION:
|
|
103
|
+
raise PersistenceError(
|
|
104
|
+
f"Unsupported recording schema_version {version!r} in {path}: "
|
|
105
|
+
f"this reader supports version {SCHEMA_VERSION}"
|
|
106
|
+
)
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def _serialize(recording: WorkflowRecording) -> dict[str, Any]:
|
|
110
|
+
"""Convert a WorkflowRecording to a JSON-serializable dict."""
|
|
111
|
+
extract_as_map = recording.extract_as_map or {}
|
|
112
|
+
return {
|
|
113
|
+
"schema_version": SCHEMA_VERSION,
|
|
114
|
+
"exchanges": [
|
|
115
|
+
_serialize_exchange(ex, extract_as_map.get(i))
|
|
116
|
+
for i, ex in enumerate(recording.exchanges)
|
|
117
|
+
],
|
|
118
|
+
"events": [_serialize_event(ev) for ev in recording.events],
|
|
119
|
+
"target_url": recording.target_url,
|
|
120
|
+
"started_at": recording.started_at,
|
|
121
|
+
"ended_at": recording.ended_at,
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
def _serialize_exchange(
|
|
126
|
+
exchange: HttpExchange,
|
|
127
|
+
extract_as: dict[str, str] | None,
|
|
128
|
+
) -> dict[str, Any]:
|
|
129
|
+
"""Serialize one HttpExchange to a JSON-compatible dict.
|
|
130
|
+
|
|
131
|
+
Emits the step's extract_as declarations so load_recording can rebuild
|
|
132
|
+
extract_as_map, keeping save and load inverse.
|
|
133
|
+
"""
|
|
134
|
+
entry: dict[str, Any] = {
|
|
135
|
+
"request": _serialize_request(exchange.request),
|
|
136
|
+
"response": _serialize_response(exchange.response),
|
|
137
|
+
"timestamp": exchange.timestamp,
|
|
138
|
+
}
|
|
139
|
+
if exchange.inject_cookies:
|
|
140
|
+
entry["inject_cookies"] = dict(exchange.inject_cookies)
|
|
141
|
+
if extract_as:
|
|
142
|
+
entry["extract_as"] = dict(extract_as)
|
|
143
|
+
return entry
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def _serialize_body(body: bytes | None) -> str | dict[str, str] | None:
|
|
147
|
+
"""Represent a body as JSON: null when absent, a UTF-8 string when the
|
|
148
|
+
octets are text, or a base64 object otherwise. Bytes survive unchanged.
|
|
149
|
+
"""
|
|
150
|
+
if body is None:
|
|
151
|
+
return None
|
|
152
|
+
try:
|
|
153
|
+
return body.decode("utf-8")
|
|
154
|
+
except UnicodeDecodeError:
|
|
155
|
+
return {"encoding": "base64", "data": base64.b64encode(body).decode("ascii")}
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
def _serialize_request(request: HttpRequest) -> dict[str, Any]:
|
|
159
|
+
"""Serialize one HttpRequest to a JSON-compatible dict."""
|
|
160
|
+
return {
|
|
161
|
+
"method": request.method.value,
|
|
162
|
+
"url": request.url,
|
|
163
|
+
"headers": request.headers,
|
|
164
|
+
"body": _serialize_body(request.body),
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
def _serialize_response(response: HttpResponse) -> dict[str, Any]:
|
|
169
|
+
"""Serialize one HttpResponse to a JSON-compatible dict."""
|
|
170
|
+
return {
|
|
171
|
+
"status_code": response.status_code,
|
|
172
|
+
"headers": response.headers,
|
|
173
|
+
"body": _serialize_body(response.body),
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
def _serialize_event(event: RecordedEvent) -> dict[str, Any]:
|
|
178
|
+
"""Serialize one RecordedEvent to a JSON-compatible dict."""
|
|
179
|
+
return {
|
|
180
|
+
"event_type": event.event_type.value,
|
|
181
|
+
"selector": event.selector,
|
|
182
|
+
"value": event.value,
|
|
183
|
+
"timestamp": event.timestamp,
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
|
|
187
|
+
def _parse_extract_as_map(raw_exchanges: list[dict[str, Any]]) -> ExtractAsMap:
|
|
188
|
+
"""Build per-step extract_as declarations from raw JSON."""
|
|
189
|
+
result: ExtractAsMap = {}
|
|
190
|
+
for i, ex_data in enumerate(raw_exchanges):
|
|
191
|
+
ea = ex_data.get("extract_as")
|
|
192
|
+
if ea is None:
|
|
193
|
+
continue
|
|
194
|
+
if isinstance(ea, str):
|
|
195
|
+
result[i] = {ea: ""}
|
|
196
|
+
elif isinstance(ea, dict):
|
|
197
|
+
result[i] = dict(ea)
|
|
198
|
+
return result
|
|
199
|
+
|
|
200
|
+
|
|
201
|
+
def _wrap_placeholders(text: str, placeholders: set[str]) -> str:
|
|
202
|
+
"""Wrap bare placeholder names with {..} for inject_value matching."""
|
|
203
|
+
for name in placeholders:
|
|
204
|
+
pattern = r"(?<!\{)" + re.escape(name) + r"(?!\})"
|
|
205
|
+
text = re.sub(pattern, "{" + name + "}", text)
|
|
206
|
+
return text
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
def _parse_cookie_header(header: str) -> dict[str, str]:
|
|
210
|
+
"""Parse a Cookie header into a name-to-value mapping.
|
|
211
|
+
|
|
212
|
+
Splits on ``;`` alone so morsels joined without a trailing space
|
|
213
|
+
(valid per RFC 6265) are recovered.
|
|
214
|
+
"""
|
|
215
|
+
cookies: dict[str, str] = {}
|
|
216
|
+
for morsel in header.split(";"):
|
|
217
|
+
name, _, value = morsel.partition("=")
|
|
218
|
+
if name.strip():
|
|
219
|
+
cookies[name.strip()] = value.strip()
|
|
220
|
+
return cookies
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
def _reconstruct_body(raw: str | dict[str, Any] | None) -> bytes | None:
|
|
224
|
+
"""Inverse of _serialize_body: null to None, string to UTF-8 bytes,
|
|
225
|
+
base64 object to decoded bytes.
|
|
226
|
+
"""
|
|
227
|
+
if raw is None:
|
|
228
|
+
return None
|
|
229
|
+
if isinstance(raw, dict):
|
|
230
|
+
return base64.b64decode(raw["data"])
|
|
231
|
+
return raw.encode("utf-8")
|
|
232
|
+
|
|
233
|
+
|
|
234
|
+
def _reconstruct_request(
|
|
235
|
+
req_data: dict[str, Any],
|
|
236
|
+
placeholders: set[str] | None,
|
|
237
|
+
) -> HttpRequest:
|
|
238
|
+
"""Reconstruct an HttpRequest, wrapping placeholder names with braces."""
|
|
239
|
+
url = req_data["url"]
|
|
240
|
+
headers = dict(req_data.get("headers", {}))
|
|
241
|
+
body_raw = req_data.get("body")
|
|
242
|
+
if placeholders:
|
|
243
|
+
url = _wrap_placeholders(url, placeholders)
|
|
244
|
+
headers = {k: _wrap_placeholders(v, placeholders) for k, v in headers.items()}
|
|
245
|
+
if isinstance(body_raw, str):
|
|
246
|
+
body_raw = _wrap_placeholders(body_raw, placeholders)
|
|
247
|
+
return HttpRequest(
|
|
248
|
+
method=HttpMethod(req_data["method"]),
|
|
249
|
+
url=url,
|
|
250
|
+
headers=headers,
|
|
251
|
+
body=_reconstruct_body(body_raw),
|
|
252
|
+
)
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
def _reconstruct_response(resp_data: dict[str, Any]) -> HttpResponse:
|
|
256
|
+
"""Reconstruct an HttpResponse from JSON dict."""
|
|
257
|
+
body = _reconstruct_body(resp_data.get("body"))
|
|
258
|
+
return HttpResponse(
|
|
259
|
+
status_code=resp_data["status_code"],
|
|
260
|
+
headers=resp_data.get("headers", {}),
|
|
261
|
+
body=body if body is not None else b"",
|
|
262
|
+
)
|
|
263
|
+
|
|
264
|
+
|
|
265
|
+
def _reconstruct_exchange(
|
|
266
|
+
data: dict[str, Any],
|
|
267
|
+
placeholders: set[str] | None = None,
|
|
268
|
+
) -> HttpExchange:
|
|
269
|
+
"""Reconstruct an HttpExchange from JSON dict."""
|
|
270
|
+
request = _reconstruct_request(data["request"], placeholders)
|
|
271
|
+
inject_cookies: dict[str, str] = dict(data.get("inject_cookies", {}))
|
|
272
|
+
if not inject_cookies and "cookie" in request.headers:
|
|
273
|
+
inject_cookies = _parse_cookie_header(request.headers["cookie"])
|
|
274
|
+
return HttpExchange(
|
|
275
|
+
request=request,
|
|
276
|
+
response=_reconstruct_response(data["response"]),
|
|
277
|
+
timestamp=data.get("timestamp", 0.0),
|
|
278
|
+
inject_cookies=inject_cookies,
|
|
279
|
+
)
|
|
280
|
+
|
|
281
|
+
|
|
282
|
+
def _reconstruct_event(data: dict[str, Any]) -> RecordedEvent:
|
|
283
|
+
"""Reconstruct a RecordedEvent from JSON dict."""
|
|
284
|
+
return RecordedEvent(
|
|
285
|
+
event_type=EventType(data["event_type"]),
|
|
286
|
+
timestamp=data["timestamp"],
|
|
287
|
+
selector=data["selector"],
|
|
288
|
+
value=data.get("value"),
|
|
289
|
+
)
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
"""Recording data types — EventType, RecordedEvent, WorkflowRecording."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import enum
|
|
6
|
+
from dataclasses import dataclass
|
|
7
|
+
|
|
8
|
+
from krill_core._http import HttpExchange
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
class EventType(enum.Enum):
|
|
12
|
+
"""Categories of user interaction events captured during browser recording."""
|
|
13
|
+
|
|
14
|
+
CLICK = "CLICK"
|
|
15
|
+
SCROLL = "SCROLL"
|
|
16
|
+
INPUT = "INPUT"
|
|
17
|
+
SUBMIT = "SUBMIT"
|
|
18
|
+
NAVIGATION = "NAVIGATION"
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
@dataclass(frozen=True)
|
|
22
|
+
class RecordedEvent:
|
|
23
|
+
"""A single user interaction event captured during a browser recording session."""
|
|
24
|
+
|
|
25
|
+
event_type: EventType
|
|
26
|
+
timestamp: float
|
|
27
|
+
selector: str
|
|
28
|
+
value: str | None = None
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
ExtractAsMap = dict[int, dict[str, str]]
|
|
32
|
+
"""Per-step declarative extraction hints: ``{step_idx: {placeholder_name: source_path}}``."""
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
@dataclass(frozen=True)
|
|
36
|
+
class WorkflowRecording:
|
|
37
|
+
"""The raw, timestamped capture of a complete user interaction session."""
|
|
38
|
+
|
|
39
|
+
exchanges: list[HttpExchange]
|
|
40
|
+
events: list[RecordedEvent]
|
|
41
|
+
target_url: str
|
|
42
|
+
started_at: float
|
|
43
|
+
ended_at: float
|
|
44
|
+
extract_as_map: ExtractAsMap | None = None
|
|
File without changes
|