# Copyright (c) 2026 Storm Dragon
# SPDX-License-Identifier: GPL-3.0-or-later
"""Experimental command/presentation SDK. stdout is reserved for the protocol.

Interaction form dictionaries may set secret=True on entries (kind=2). The host
masks editing output and disallows copy/cut; successful submissions still carry
plaintext values to the continuation. Never log or present those values. Secret
entries cannot be used in persistent preference pages; older hosts reject them.

Protocol 1.1 interactive commands can request a reader-owned consent dialog with
{"remote": {"role": "controller", "grants": ["remote-present"]}, "next": "approved"}.
The request may include "optional_grants" for installed, role-valid services
to offer in the same unchecked reader approval form. Missing optional grants
are omitted; missing required grants fail. No access is approved implicitly.
The continuation receives "remote" metadata after explicit local approval, or
"cancelled": True on denial. Match approval to the actual SessionClient event;
neither a request dictionary nor submitted metadata is itself consent. This
interaction addition requires the matching updated reader.

After remote.open, an explicit return-to-desktop action can finish with
{"remote_background": {"lease": lease["lease"], "epoch": lease["epoch"]},
 "done": True}. The host checks an already-open lease belonging to this process;
this neither grants consent nor renews it. Keep heartbeating and provide an
explicit status/disconnect command. Other interaction effects cannot accompany
this terminal result, except ordinary speech/Braille presentation. Cancellation
and normal form closure still end setup. Older hosts reject this addition.
"""

import json
import sys
import threading
from dataclasses import dataclass, field

MAX_FRAME = 64 * 1024


class ProtocolError(Exception):
    pass


@dataclass
class Command:
    id: str
    title: str
    description: str
    handle: object
    bindings: list = field(default_factory=list)
    presentation: bool = False
    interaction: bool = False
    settings: bool = False
    reader: bool = False

    def declaration(self):
        declaration = {"id": self.id, "title": self.title, "description": self.description,
                       "bindings": self.bindings}
        if self.presentation:
            declaration["presentation"] = True
        for name in ("interaction", "settings", "reader"):
            if getattr(self, name):
                declaration[name] = True
        return declaration


def present(speech="", braille="", uninterruptible=False):
    """Return independent text messages from a presentation-enabled command."""
    if type(uninterruptible) is not bool or (uninterruptible and not speech):
        raise ValueError("Uninterruptible output requires speech and a boolean option")
    result = {key: text for key, text in (("speech", speech), ("braille", braille)) if text}
    if uninterruptible:
        result["uninterruptible"] = True
    return result


def _object(pairs):
    result = {}
    for key, value in pairs:
        if key in result:
            raise ProtocolError("Duplicate key")
        result[key] = value
    return result


def _depth(value, depth=0):
    if depth > 32:
        raise ProtocolError("JSON nesting limit")
    if isinstance(value, (dict, list)):
        for child in value.values() if isinstance(value, dict) else value:
            _depth(child, depth + 1)


def _constant(value):
    raise ProtocolError("Invalid JSON number")


def _encode(value):
    _depth(value)
    return json.dumps(value, ensure_ascii=False, allow_nan=False,
                      separators=(",", ":")).encode("utf-8")


def _fields(value, required, optional=()):
    if (not isinstance(value, dict) or not set(required) <= value.keys()
            or value.keys() - set(required) - set(optional)):
        raise ProtocolError("Invalid fields")


def serve(commands, inputStream=None, outputStream=None, extensions=None, session_client=None):
    """Run in a dedicated child, then exit. Handlers receive (cancelled, arguments).

    cancelled is a threading.Event shared by the session. Up to eight handlers
    run concurrently. Shutdown/EOF sets it and joins handlers; the host terminates
    children that ignore cancellation. Exceptions become generic RPC errors.
    Streams are binary, owned by this call, and closed on return.
    """
    inputStream = inputStream if inputStream is not None else sys.stdin.buffer
    outputStream = outputStream if outputStream is not None else sys.stdout.buffer
    cancelled = threading.Event()
    writeLock = threading.Lock()
    workers = []
    slots = threading.BoundedSemaphore(8)
    client_started = False
    if session_client is not None:
        from .session import valid_negotiation

    def write_reply(requestId, value=None, failed=False, release=None):
        reply = {"jsonrpc": "2.0", "id": requestId}
        if failed:
            reply["error"] = {"code": -32603, "message": "Command failed"}
        else:
            reply["result"] = value
        try:
            frame = _encode(reply)
            if len(frame) > MAX_FRAME:
                raise ValueError()
        except (ValueError, TypeError, UnicodeError, RecursionError, ProtocolError):
            frame = _encode({"jsonrpc": "2.0", "id": requestId, "error": {
                "code": -32603, "message": "Invalid or oversized result"}})
        if session_client is not None:
            if release is not None:
                release()
            session_client._enqueue(frame + b"\n")
            return
        with writeLock:
            # Bound eight handlers/waiting replies plus one serialized writer.
            if release is not None:
                release()
            if not cancelled.is_set():
                outputStream.write(frame + b"\n")
                outputStream.flush()

    def invoke(requestId, handler, arguments):
        released = False

        def release_slot():
            nonlocal released
            if not released:
                slots.release()
                released = True

        try:
            value = handler(cancelled, arguments)
        except BaseException:
            value, failed = None, True
        else:
            failed = False
        try:
            write_reply(requestId, value, failed, release_slot)
        except (OSError, ValueError, ProtocolError, SessionError):
            cancelled.set()
            if session_client is not None:
                session_client._abort()
        finally:
            release_slot()

    try:
        if session_client is not None:
            session_client._start(cancelled, inputStream, outputStream)
            client_started = True
        commands = list(commands)
        handlers = {command.id: command.handle for command in commands}
        if (not 1 <= len(commands) <= 32 or len(handlers) != len(commands)
                or any(not key or not callable(value) for key, value in handlers.items())):
            raise ProtocolError("Invalid commands")
        if (sum(command.settings for command in commands) > 1
                or any(command.interaction and not command.presentation
                       or command.settings and not command.interaction
                       or command.reader and not command.interaction for command in commands)):
            raise ProtocolError("Invalid command capabilities")
        session, active, sequence = None, False, 0
        while not cancelled.is_set():
            frame = session_client._readline() if session_client is not None else inputStream.readline(MAX_FRAME + 2)
            if not frame:
                return
            if not frame.endswith(b"\n") or len(frame) > MAX_FRAME + 1:
                raise ProtocolError("Invalid frame size or termination")
            try:
                message = json.loads(frame.decode("utf-8"), object_pairs_hook=_object,
                                     parse_constant=_constant)
                _depth(message)
            except (ValueError, UnicodeError, RecursionError) as error:
                raise ProtocolError("Invalid JSON") from error
            if session_client is not None and isinstance(message, dict) and "method" not in message:
                session_client._reply(message)
                continue
            _fields(message, ("jsonrpc", "method"), ("id", "params"))
            if message["jsonrpc"] != "2.0":
                raise ProtocolError("Invalid JSON-RPC version")
            requestId = message.get("id", "")
            if requestId:
                if (not isinstance(requestId, str) or not requestId.isascii()
                        or not requestId.isdecimal() or len(requestId) > 20
                        or not sequence < int(requestId) < 2**64
                        or str(int(requestId)) != requestId):
                    raise ProtocolError("Invalid request sequence")
                sequence = int(requestId)
            elif "id" in message:
                raise ProtocolError("Invalid request ID")
            method, params = message["method"], message.get("params")
            if method == "initialize":
                _fields(params, ("protocol", "session", "apis", "capabilities"))
                version = params["protocol"]
                expected_minor = 1 if session_client is not None else 0
                apis, capabilities = params["apis"], params["capabilities"]
                valid_apis = (valid_negotiation(apis, capabilities) if session_client is not None else
                              apis in (["commands"], ["commands", "presentation"],
                                       ["commands", "presentation", "interaction"],
                                       ["commands", "presentation", "interaction", "reader-settings"])
                              and capabilities == apis)
                if (session is not None or not requestId or version != {"major": 1, "minor": expected_minor}
                        or any(type(value) is not int for value in version.values())
                        or not isinstance(params["session"], str) or not params["session"]
                        or len(params["session"].encode("utf-8")) > 128
                        or not valid_apis
                        or (any(command.presentation for command in commands)
                            and "presentation" not in apis)
                        or (any(command.interaction for command in commands) and "interaction" not in apis)
                        or ((extensions is not None or any(command.reader for command in commands))
                            and "reader-settings" not in apis)):
                    raise ProtocolError("Invalid initialization")
                session = params["session"]
                registration = {"protocol": version, "session": session,
                                "commands": [command.declaration() for command in commands]}
                if extensions is not None:
                    registration["extensions"] = extensions
                write_reply(requestId, registration)
            elif method == "initialized":
                _fields(params, ("session",))
                if session is None or active or requestId or params["session"] != session:
                    raise ProtocolError("Invalid activation")
                active = True
                if session_client is not None:
                    with session_client._lock:
                        session_client._active = True
            elif method == "session.event":
                if not active or requestId or session_client is None:
                    raise ProtocolError("Unnegotiated event")
                session_client._event(params)
            elif method == "command.invoke":
                _fields(params, ("command", "arguments"))
                if (not active or not requestId or not isinstance(params["command"], str)
                        or params["command"] not in handlers
                        or len(_encode(params["arguments"])) > (48 if next(
                            command.reader for command in commands if command.id == params["command"]) else 16) * 1024):
                    raise ProtocolError("Invalid invocation")
                workers = [worker for worker in workers if worker.is_alive()]
                if not slots.acquire(blocking=False):
                    raise ProtocolError("Command limit")
                worker = threading.Thread(target=invoke, args=(requestId,
                    handlers[params["command"]], params["arguments"]))
                workers.append(worker)
                worker.start()
            elif method == "shutdown":
                if requestId or params is not None:
                    raise ProtocolError("Invalid shutdown")
                return
            else:
                raise ProtocolError("Unknown method")
    finally:
        cancelled.set()
        if client_started:
            session_client._finish()
        # Join before closing buffered stdout: a blocked writer must remain
        # subject to the host deadline rather than race a Python buffer close.
        for worker in workers:
            worker.join()
        if client_started:
            session_client._close()
        inputStream.close()
        outputStream.close()

# Imported after helpers to keep the protocol 1.0 API compatible.
from .session import SessionClient, SessionError