librepost-app 0.1.0__py3-none-any.whl

librepost/__init__.py

@@ -0,0 +1,3 @@
+"""A free, local-first API client."""
+
+__version__ = "0.1.0"

librepost/__main__.py

@@ -0,0 +1,3 @@
+from .cli import app
+
+app(prog_name="librepost")

librepost/cli.py

@@ -0,0 +1,301 @@
+from __future__ import annotations
+
+import contextlib
+import getpass
+import secrets
+import socket
+import sys
+import webbrowser
+from pathlib import Path
+from typing import Annotated
+
+import httpx
+import typer
+from rich.console import Console
+
+from . import __version__, environments, leakcheck, runner, secretstore
+from .environments import EnvFileError
+from .httpfile import HttpFileError, parse
+from .secretstore import SecretError
+from .template import TemplateError
+
+app = typer.Typer(
+    help="A free, local-first API client. Requests are .http files; secrets stay in your keychain.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+secret_app = typer.Typer(help="Store secrets in the OS keychain for {{secret:keychain/<name>}}.")
+app.add_typer(secret_app, name="secret")
+
+out = Console(highlight=False)
+err = Console(stderr=True, highlight=False)
+
+DEFAULT_PORT = 8765
+
+
+def _version(value: bool) -> None:
+    if value:
+        out.print(f"librepost {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool, typer.Option("--version", callback=_version, is_eager=True, help="Show the version.")
+    ] = False,
+) -> None:
+    pass
+
+
+def _bind(port: int) -> socket.socket:
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    if sys.platform != "win32":
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    try:
+        sock.bind(("127.0.0.1", port))
+    except OSError:
+        if port == 0:
+            raise
+        sock.bind(("127.0.0.1", 0))
+    return sock
+
+
+@app.command()
+def ui(
+    directory: Annotated[
+        Path, typer.Argument(help="Folder holding your .http files.", file_okay=False)
+    ] = Path("."),
+    port: Annotated[
+        int, typer.Option(help="Port on 127.0.0.1 (a free one is picked if it's taken).")
+    ] = DEFAULT_PORT,
+    open_browser: Annotated[
+        bool, typer.Option("--open/--no-open", help="Open the UI in your browser.")
+    ] = True,
+) -> None:
+    """Start the UI on 127.0.0.1 and open it in your browser."""
+    import uvicorn
+
+    from .server import create_app
+
+    if not directory.is_dir():
+        err.print(f"[red]Not a folder:[/] {directory}")
+        raise typer.Exit(2)
+    sock = _bind(port)
+    port = sock.getsockname()[1]
+    token = secrets.token_urlsafe(32)
+    url = f"http://127.0.0.1:{port}/?token={token}"
+    application = create_app(directory, port=port, token=token)
+
+    out.print(f"[bold green]librepost {__version__}[/] serving [bold]{directory.resolve()}[/]")
+    out.print(f"Open: [link={url}]{url}[/link]")
+    out.print(
+        "[dim]Only this machine can connect, and only with the link above. Ctrl+C stops it.[/]"
+    )
+    if open_browser:
+        webbrowser.open(url)
+    config = uvicorn.Config(application, log_level="warning", access_log=False, server_header=False)
+    with contextlib.suppress(KeyboardInterrupt):
+        uvicorn.Server(config).run(sockets=[sock])
+
+
+@app.command()
+def run(
+    file: Annotated[Path, typer.Argument(help="An .http file.", exists=True, dir_okay=False)],
+    name: Annotated[
+        str | None, typer.Option("--name", "-n", help="Request name (default: the first one).")
+    ] = None,
+    env: Annotated[str | None, typer.Option("--env", "-e", help="Environment to use.")] = None,
+    verbose: Annotated[
+        bool, typer.Option("--verbose", "-v", help="Show the request and response headers.")
+    ] = False,
+    fail: Annotated[
+        bool, typer.Option("--fail", "-f", help="Exit with status 22 on HTTP 4xx/5xx.")
+    ] = False,
+    insecure: Annotated[
+        bool, typer.Option("--insecure", "-k", help="Don't verify TLS certificates.")
+    ] = False,
+    timeout: Annotated[float, typer.Option(help="Timeout in seconds.")] = 30.0,
+) -> None:
+    """Send a request from an .http file and print the response."""
+    try:
+        httpfile = parse(file.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError) as exc:
+        err.print(f"[red]Can't read {file}:[/] {exc}")
+        raise typer.Exit(2) from None
+    if not httpfile.requests:
+        err.print(f"[red]No requests in {file}.[/]")
+        raise typer.Exit(2)
+    if name is None:
+        request = httpfile.requests[0]
+    else:
+        matches = [r for r in httpfile.requests if r.name == name]
+        if not matches:
+            names = ", ".join(r.name for r in httpfile.requests if r.name) or "(none)"
+            err.print(f"[red]No request named {name!r}.[/] Names in this file: {names}")
+            raise typer.Exit(2)
+        request = matches[0]
+
+    root = _workspace_root(file)
+    try:
+        variables = dict(httpfile.variables)
+        variables.update(environments.variables(root, env))
+        prepared = runner.prepare(request, variables)
+    except (EnvFileError, TemplateError, SecretError, HttpFileError) as exc:
+        err.print(f"[red]{exc}[/]")
+        raise typer.Exit(2) from None
+
+    if verbose:
+        for line in prepared.masked().split("\n\n", 1)[0].splitlines():
+            err.print(f"[dim]> {line}[/]")
+        err.print()
+    try:
+        result = runner.send(prepared, timeout=timeout, verify=not insecure)
+    except httpx.HTTPError as exc:
+        err.print(f"[red]{type(exc).__name__}:[/] {prepared.renderer.mask(str(exc))}")
+        raise typer.Exit(1) from None
+
+    colour = "green" if result.status < 400 else "red"
+    err.print(
+        f"[bold {colour}]{result.status} {result.reason}[/] "
+        f"[dim]{result.elapsed_ms:.0f} ms, {len(result.body)} bytes[/]"
+    )
+    if verbose:
+        for key, value in result.headers:
+            err.print(f"[dim]< {key}: {value}[/]")
+        err.print()
+    sys.stdout.buffer.write(result.body)
+    if result.body and not result.body.endswith(b"\n") and sys.stdout.isatty():
+        sys.stdout.write("\n")
+    sys.stdout.flush()
+    if fail and result.status >= 400:
+        raise typer.Exit(22)
+
+
+def _workspace_root(file: Path) -> Path:
+    """The nearest folder above the file that has an environment file, else the file's folder."""
+    start = file.resolve().parent
+    for folder in (start, *start.parents):
+        if (folder / environments.PUBLIC_FILE).is_file() or (
+            folder / environments.PRIVATE_FILE
+        ).is_file():
+            return folder
+        if (folder / ".git").exists():
+            break
+    return start
+
+
+@app.command()
+def check(
+    paths: Annotated[
+        list[Path] | None, typer.Argument(help="Files or folders (default: current folder).")
+    ] = None,
+) -> None:
+    """Find literal secrets in .http and environment files. Exits 1 if any are found."""
+    targets = paths or [Path(".")]
+    leaks = leakcheck.scan(targets, display_root=Path.cwd())
+    for leak in leaks:
+        out.print(f"[bold]{leak.path}:{leak.line}[/] [red]{leak.rule}[/] {leak.message}")
+    if leaks:
+        out.print(
+            f"\n[red]{len(leaks)} possible secret(s).[/] Use {{{{secret:...}}}} references instead."
+        )
+        raise typer.Exit(1)
+    out.print("[green]No literal secrets found.[/]")
+
+
+EXAMPLE_ENV = """{
+  "dev": {
+    "baseUrl": "https://httpbin.org",
+    "token": "{{secret:keychain/demo-token}}"
+  }
+}
+"""
+
+EXAMPLE_HTTP = """# Requests are plain text: commit them, review them in pull requests, share them.
+# @name get-example
+GET {{baseUrl}}/get?hello=world
+Accept: application/json
+
+###
+
+# The token comes from your OS keychain. Add it with: librepost secret set demo-token
+# @name bearer-example
+GET {{baseUrl}}/bearer
+Authorization: Bearer {{token}}
+
+###
+
+# @name post-example
+POST {{baseUrl}}/post
+Content-Type: application/json
+
+{
+  "id": "{{$uuid}}",
+  "sentAt": "{{$isoTimestamp}}"
+}
+"""
+
+
+@app.command()
+def init(
+    directory: Annotated[Path, typer.Argument(file_okay=False)] = Path("."),
+) -> None:
+    """Create an example environment file and requests, and gitignore the private env file."""
+    directory.mkdir(parents=True, exist_ok=True)
+    written = []
+    for rel, text in (
+        (environments.PUBLIC_FILE, EXAMPLE_ENV),
+        ("requests/example.http", EXAMPLE_HTTP),
+    ):
+        path = directory / rel
+        if path.exists():
+            out.print(f"[dim]Kept existing {rel}[/]")
+            continue
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text, encoding="utf-8", newline="\n")
+        written.append(rel)
+
+    gitignore = directory / ".gitignore"
+    existing = gitignore.read_text(encoding="utf-8") if gitignore.exists() else ""
+    if environments.PRIVATE_FILE not in existing.splitlines():
+        prefix = "" if not existing or existing.endswith("\n") else "\n"
+        with gitignore.open("a", encoding="utf-8", newline="\n") as f:
+            f.write(
+                f"{prefix}# librepost: per-machine values, never committed\n{environments.PRIVATE_FILE}\n"
+            )
+        written.append(".gitignore")
+
+    for rel in written:
+        out.print(f"[green]Wrote[/] {rel}")
+    out.print("\nNext: [bold]librepost ui[/]  (and optionally: librepost secret set demo-token)")
+
+
+@secret_app.command("set")
+def secret_set(name: Annotated[str, typer.Argument(help="Secret name.")]) -> None:
+    """Store a secret in the OS keychain. The value is read without echoing it."""
+    value = (
+        getpass.getpass(f"Value for {name}: ")
+        if sys.stdin.isatty()
+        else sys.stdin.readline().rstrip("\n")
+    )
+    if not value:
+        err.print("[red]Empty value; nothing stored.[/]")
+        raise typer.Exit(2)
+    try:
+        secretstore.store(name, value)
+    except SecretError as exc:
+        err.print(f"[red]{exc}[/]")
+        raise typer.Exit(1) from None
+    out.print(f"[green]Stored[/] {name}. Use it as {{{{secret:keychain/{name}}}}}")
+
+
+@secret_app.command("delete")
+def secret_delete(name: Annotated[str, typer.Argument(help="Secret name.")]) -> None:
+    """Remove a secret from the OS keychain."""
+    try:
+        secretstore.delete(name)
+    except SecretError as exc:
+        err.print(f"[red]{exc}[/]")
+        raise typer.Exit(1) from None
+    out.print(f"[green]Deleted[/] {name}.")

librepost/environments.py

@@ -0,0 +1,71 @@
+"""Environments, in the JetBrains HTTP Client format.
+
+`http-client.env.json` is committed and holds shared, non-secret values.
+`http-client.private.env.json` is gitignored and overrides it per machine:
+
+    {
+      "$shared": {"apiVersion": "v2"},
+      "dev":     {"baseUrl": "https://dev.example.com", "token": "{{secret:keychain/dev-token}}"},
+      "prod":    {"baseUrl": "https://api.example.com"}
+    }
+
+`$shared` values apply to every environment.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+PUBLIC_FILE = "http-client.env.json"
+PRIVATE_FILE = "http-client.private.env.json"
+SHARED = "$shared"
+
+
+class EnvFileError(ValueError):
+    pass
+
+
+def _read(path: Path) -> dict[str, dict[str, str]]:
+    if not path.is_file():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise EnvFileError(f"Can't read {path.name}: {exc}") from None
+    if not isinstance(data, dict):
+        raise EnvFileError(f"{path.name} must contain a JSON object of environments.")
+    result: dict[str, dict[str, str]] = {}
+    for env, values in data.items():
+        if not isinstance(values, dict):
+            raise EnvFileError(f"{path.name}: environment {env!r} must be an object.")
+        result[env] = {str(k): _to_text(v) for k, v in values.items()}
+    return result
+
+
+def _to_text(value: object) -> str:
+    if isinstance(value, str):
+        return value
+    return json.dumps(value)
+
+
+def load(root: Path) -> dict[str, dict[str, str]]:
+    """All environments under `root`, with private values overriding public ones."""
+    merged = _read(root / PUBLIC_FILE)
+    for env, values in _read(root / PRIVATE_FILE).items():
+        merged.setdefault(env, {}).update(values)
+    return merged
+
+
+def names(root: Path) -> list[str]:
+    return sorted(env for env in load(root) if env != SHARED)
+
+
+def variables(root: Path, env: str | None) -> dict[str, str]:
+    envs = load(root)
+    result = dict(envs.get(SHARED, {}))
+    if env:
+        if env not in envs:
+            raise EnvFileError(f"Unknown environment {env!r}.")
+        result.update(envs[env])
+    return result

librepost/httpfile.py

@@ -0,0 +1,205 @@
+"""Read and write `.http` files, the plain-text request format used by the JetBrains HTTP
+Client and the VS Code REST Client.
+
+A file holds one or more requests separated by lines starting with `###`:
+
+    @baseUrl = https://example.com
+
+    # @name login
+    POST {{baseUrl}}/login
+    Content-Type: application/json
+
+    {"user": "alice"}
+
+    ###
+
+    GET {{baseUrl}}/me
+
+Supported: `# @name`, `// comments`, `@var = value` file variables, multi-line query
+continuations (indented lines starting with `?` or `&`) and `HTTP/x` suffixes. Response
+handler scripts (`> {% ... %}`) and output redirects (`>> file`, `<> file`) are kept
+when the file is saved, but librepost does not run them.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+METHODS = ("GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "TRACE", "CONNECT")
+
+_SEPARATOR = re.compile(r"^###(.*)$")
+_REQUEST_LINE = re.compile(
+    r"^(?P<method>[A-Z]+)\s+(?P<url>\S.*?)(?:\s+HTTP/\d(?:\.\d)?)?\s*$",
+)
+_COMMENT = re.compile(r"^\s*(#|//)")
+_NAME = re.compile(r"^\s*(?:#|//)\s*@name\s*[= ]\s*(?P<name>\S.*?)\s*$")
+_FILE_VARIABLE = re.compile(r"^@(?P<name>[A-Za-z_][\w.-]*)\s*=\s*(?P<value>.*?)\s*$")
+_URL_CONTINUATION = re.compile(r"^\s+[?&]")
+# Lines that end the body: response handlers and output redirects.
+_TRAILER = re.compile(r"^(> \{%|> \S|>>!? |<> )")
+
+
+class HttpFileError(ValueError):
+    """A request can't be written as valid `.http` text."""
+
+
+@dataclass
+class Request:
+    method: str = "GET"
+    url: str = ""
+    headers: list[tuple[str, str]] = field(default_factory=list)
+    body: str = ""
+    name: str = ""
+    # Comment lines above the request line (other than `@name`), kept verbatim.
+    comments: list[str] = field(default_factory=list)
+    # Response handlers and redirects after the body, kept verbatim but never run.
+    trailer: str = ""
+
+    @property
+    def label(self) -> str:
+        return self.name or f"{self.method} {self.url}"
+
+
+@dataclass
+class HttpFile:
+    requests: list[Request] = field(default_factory=list)
+    variables: dict[str, str] = field(default_factory=dict)
+
+
+def parse(text: str) -> HttpFile:
+    result = HttpFile()
+    for separator_name, block in _blocks(text):
+        request = _parse_block(block, result.variables)
+        if request is None:
+            continue
+        if not request.name and separator_name:
+            request.name = separator_name
+        result.requests.append(request)
+    return result
+
+
+def _blocks(text: str) -> list[tuple[str, list[str]]]:
+    blocks: list[tuple[str, list[str]]] = [("", [])]
+    for line in text.replace("\r\n", "\n").split("\n"):
+        match = _SEPARATOR.match(line)
+        if match:
+            blocks.append((match.group(1).strip(), []))
+        else:
+            blocks[-1][1].append(line)
+    return blocks
+
+
+def _parse_block(lines: list[str], variables: dict[str, str]) -> Request | None:
+    request = Request()
+    i = 0
+    # Comments, names and file variables before the request line.
+    while i < len(lines):
+        line = lines[i]
+        if not line.strip():
+            i += 1
+            continue
+        name = _NAME.match(line)
+        if name:
+            request.name = name.group("name")
+        elif _COMMENT.match(line):
+            request.comments.append(line.rstrip())
+        else:
+            variable = _FILE_VARIABLE.match(line)
+            if not variable:
+                break
+            variables[variable.group("name")] = variable.group("value")
+        i += 1
+    if i == len(lines):
+        return None
+
+    request_line = lines[i].strip()
+    match = _REQUEST_LINE.match(request_line)
+    if match and match.group("method") in METHODS:
+        request.method = match.group("method")
+        request.url = match.group("url")
+    else:
+        request.url = re.sub(r"\s+HTTP/\d(?:\.\d)?\s*$", "", request_line)
+    i += 1
+    while i < len(lines) and _URL_CONTINUATION.match(lines[i]):
+        request.url += lines[i].strip()
+        i += 1
+
+    while i < len(lines) and lines[i].strip():
+        line = lines[i]
+        i += 1
+        if _COMMENT.match(line):
+            continue
+        key, sep, value = line.partition(":")
+        if sep:
+            request.headers.append((key.strip(), value.strip()))
+
+    body = lines[i + 1 :] if i < len(lines) else []
+    for j, line in enumerate(body):
+        if _TRAILER.match(line):
+            request.trailer = "\n".join(body[j:]).strip("\n")
+            body = body[:j]
+            break
+    request.body = "\n".join(body).strip("\n")
+    return request
+
+
+def validate(request: Request) -> None:
+    """Raise HttpFileError if the request would not survive a save and reload."""
+    if not request.url.strip():
+        raise HttpFileError("The URL is empty.")
+    if "\n" in request.url or "\n" in request.name:
+        raise HttpFileError("The URL and name must be on one line.")
+    if not re.fullmatch(r"[A-Z]+", request.method):
+        raise HttpFileError(f"Invalid method: {request.method!r}")
+    for key, value in request.headers:
+        if not re.fullmatch(r"[!#$%&'*+.^_`|~0-9A-Za-z-]+", key):
+            raise HttpFileError(f"Invalid header name: {key!r}")
+        if "\n" in value:
+            raise HttpFileError(f"Header {key} has a line break in its value.")
+    for line in request.body.split("\n"):
+        if _SEPARATOR.match(line):
+            raise HttpFileError("A body line can't start with ###: it separates requests.")
+        if _TRAILER.match(line):
+            raise HttpFileError(
+                f"A body line can't start with {line[:3]!r}: .http files use it for response handlers."
+            )
+
+
+def dumps(httpfile: HttpFile) -> str:
+    parts: list[str] = []
+    if httpfile.variables:
+        parts.append("\n".join(f"@{k} = {v}" for k, v in httpfile.variables.items()))
+    for request in httpfile.requests:
+        validate(request)
+        lines = list(request.comments)
+        if request.name:
+            lines.append(f"# @name {request.name}")
+        lines.append(f"{request.method} {request.url}")
+        lines.extend(f"{k}: {v}" for k, v in request.headers)
+        if request.body:
+            lines.extend(["", request.body])
+        if request.trailer:
+            lines.extend(["", request.trailer])
+        parts.append("\n".join(lines))
+    if httpfile.variables and httpfile.requests:
+        head, first, *rest = parts
+        parts = [f"{head}\n\n{first}", *rest]
+    return "\n\n###\n\n".join(parts) + "\n"
+
+
+def parse_headers(text: str) -> list[tuple[str, str]]:
+    """Parse `Name: value` lines, as typed in the editor."""
+    headers = []
+    for number, line in enumerate(text.replace("\r\n", "\n").split("\n"), start=1):
+        if not line.strip():
+            continue
+        key, sep, value = line.partition(":")
+        if not sep or not key.strip():
+            raise HttpFileError(f"Header line {number} is not 'Name: value': {line.strip()!r}")
+        headers.append((key.strip(), value.strip()))
+    return headers
+
+
+def format_headers(headers: list[tuple[str, str]]) -> str:
+    return "\n".join(f"{k}: {v}" for k, v in headers)