endia 0.0.1__py3-none-any.whl

endia/__init__.py

@@ -0,0 +1,52 @@
+"""The Python client of EastIndia, which runs Hyper-V Windows virtual machines for tests, driven as Docker drives containers.
+
+Start from ``EastIndiaClient``, or ``EastIndiaClient.from_env()`` to connect where the ``endia`` CLI would. The records of
+each area live in the area's module, such as ``endia.desktop.UiElement``.
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+from ._dockerignore import IgnoreFileError
+from ._wire import Timestamp
+from .client import EastIndiaClient
+from .errors import (
+	ApiError,
+	ConnectionFailure,
+	EastIndiaApiError,
+	EastIndiaConnectionError,
+	EastIndiaError,
+	ErrorCode,
+	ExecTimeoutError,
+	MachineFailedError,
+	OperationFailedError,
+)
+from .execs import ExecResult, ExecSession, StreamKind
+from .operations import Operation, OperationHandle, OperationState
+
+try:
+	__version__ = _version("endia")
+except PackageNotFoundError:
+	__version__ = "0.0.0"
+
+__all__ = [
+	"ApiError",
+	"ConnectionFailure",
+	"EastIndiaApiError",
+	"EastIndiaClient",
+	"EastIndiaConnectionError",
+	"EastIndiaError",
+	"ErrorCode",
+	"ExecResult",
+	"ExecSession",
+	"ExecTimeoutError",
+	"IgnoreFileError",
+	"MachineFailedError",
+	"Operation",
+	"OperationFailedError",
+	"OperationHandle",
+	"OperationState",
+	"StreamKind",
+	"Timestamp",
+	"__version__",
+]

endia/_connection.py

@@ -0,0 +1,261 @@
+"""The one connection that every route group of a client shares.
+
+Over HTTPS it presents the caller's client certificate and accepts the server only through EastIndia's own authority. A request
+that changes something carries an ``Idempotency-Key`` and is sent again with the same key when its connection fails before any
+reply. This module is also the one place where a refusal becomes ``EastIndiaApiError`` and a failure to connect becomes
+``EastIndiaConnectionError``.
+"""
+
+import base64
+import binascii
+import json
+import ssl
+import time
+import uuid
+from collections.abc import Iterator
+from contextlib import ExitStack
+from dataclasses import dataclass
+from typing import IO, Any
+
+import httpx
+from websockets.exceptions import InvalidHandshake, InvalidStatus
+from websockets.sync.client import ClientConnection
+from websockets.sync.client import connect as connect_websocket
+
+from . import _wire
+from .errors import ApiError, ConnectionFailure, EastIndiaApiError, EastIndiaConnectionError
+
+IDEMPOTENCY_HEADER = "Idempotency-Key"
+ERROR_HEADER = "X-EastIndia-Error"
+"""The header that carries, as Base64 of its JSON, the error of a refusal whose answer has no body, such as a HEAD's."""
+
+JSON_MEDIA_TYPE = "application/json"
+TAR_MEDIA_TYPE = "application/x-tar"
+
+# An upload's body is read from the caller's stream, and sent, one piece of this many bytes at a time.
+_UPLOAD_CHUNK_BYTES = 1024 * 1024
+
+
+@dataclass(frozen=True, kw_only=True)
+class ConnectionSettings:
+	"""Where the service is, how it is reached, and how patiently."""
+
+	host: str
+	"""The service's host name or address, which its certificate must name."""
+
+	port: int
+	"""The service's TCP port."""
+
+	tls: ssl.SSLContext
+	"""The TLS settings: the client certificate, and the authority that the server's certificate must chain to."""
+
+	request_timeout: float
+	"""The seconds allowed to connect, and to wait for each read of an answer, where a time limit applies."""
+
+	request_retries: int
+	"""How many times a changing request is sent again after its connection failed before any reply."""
+
+	retry_delay: float
+	"""The seconds between those attempts."""
+
+	@property
+	def address(self) -> str:
+		"""The host and port, as a URL and messages write them, with an IPv6 address in brackets."""
+		return f"[{self.host}]:{self.port}" if ":" in self.host else f"{self.host}:{self.port}"
+
+
+def tls_context(ca_file: str, cert_file: str, key_file: str) -> ssl.SSLContext:
+	"""Builds the TLS settings of mutual TLS with EastIndia.
+
+	The server must present a certificate that chains to the authority in ``ca_file``, is meant for server authentication and
+	names the address the client connects to. The operating system's trust store is never consulted, and verification cannot be
+	turned off. The client presents the certificate in ``cert_file`` with its unencrypted key in ``key_file``.
+
+	Raises:
+		FileNotFoundError: One of the three files does not exist.
+		ssl.SSLError: A file does not hold a certificate, or the key does not belong to the certificate.
+	"""
+	context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+	context.minimum_version = ssl.TLSVersion.TLSv1_2
+	context.load_verify_locations(cafile=ca_file)
+	context.load_cert_chain(certfile=cert_file, keyfile=key_file)
+	return context
+
+
+def classify(error: BaseException) -> ConnectionFailure:
+	"""Gives the reason no answer came, from the exception that sending the request raised.
+
+	The exception and its causes are examined from the outermost inwards. A failed check of the server's certificate is
+	``SERVER_NOT_TRUSTED``. Any other TLS failure is ``CERTIFICATE_REFUSED``: the service refuses a client certificate with a TLS
+	alert, which under TLS 1.2 ends the handshake and under TLS 1.3 arrives on the first read. Anything else is ``UNREACHABLE``.
+	"""
+	cause: BaseException | None = error
+	while cause is not None:
+		if isinstance(cause, ssl.SSLCertVerificationError):
+			return ConnectionFailure.SERVER_NOT_TRUSTED
+		if isinstance(cause, ssl.SSLError) or "alert" in str(cause).lower():
+			return ConnectionFailure.CERTIFICATE_REFUSED
+		cause = cause.__cause__ or cause.__context__
+	return ConnectionFailure.UNREACHABLE
+
+
+def read_error(body: bytes | bytearray, header: str | None) -> ApiError | None:
+	"""Reads a refusal's error from its body, or from the ``X-EastIndia-Error`` header when the body holds none."""
+	try:
+		return _wire.read(json.loads(body), ApiError)
+	except ValueError:
+		pass
+	try:
+		return _wire.read(json.loads(base64.b64decode(header or "", validate=True)), ApiError)
+	except (ValueError, binascii.Error):
+		return None
+
+
+class Connection:
+	"""Sends the requests of every route group, and turns every failure into one of the SDK's two exceptions."""
+
+	def __init__(self, settings: ConnectionSettings, transport: httpx.BaseTransport | None = None) -> None:
+		self.settings = settings
+		self._http = httpx.Client(
+			base_url=f"https://{settings.address}",
+			verify=settings.tls,
+			timeout=settings.request_timeout,
+			transport=transport,
+		)
+
+	def close(self) -> None:
+		"""Closes the connection's sockets."""
+		self._http.close()
+
+	def read(self, path: str) -> Any:
+		"""Sends a ``GET`` and gives its parsed JSON answer. A read is never sent again."""
+		return self._send(self._http.build_request("GET", path), timed=True).json()
+
+	def head(self, path: str) -> httpx.Headers:
+		"""Sends a ``HEAD`` and gives the answer's headers; a refusal carries its error in the ``X-EastIndia-Error`` header."""
+		return self._send(self._http.build_request("HEAD", path), timed=True).headers
+
+	def change(
+		self,
+		method: str,
+		path: str,
+		*,
+		json_body: Any = None,
+		archive: IO[bytes] | None = None,
+		timed: bool = True,
+	) -> httpx.Response:
+		"""Sends a request that changes something, and gives the answer with its body read.
+
+		The request carries a new ``Idempotency-Key``. When its connection fails before any reply, it is sent again with the same key
+		up to ``request_retries`` times, ``retry_delay`` seconds apart, so that the service does the work once. An ``archive``, the
+		body of an upload, must be seekable: each attempt sends it again from where it started.
+
+		Args:
+			timed: Whether the request time-out applies. It does not for an upload, whose body can take longer to send, nor for a
+				wait that the service answers only when the wait ends.
+		"""
+		key = uuid.uuid4().hex
+		start = archive.tell() if archive is not None else 0
+		attempt = 0
+		while True:
+			request = self._build(method, path, json_body, archive, start)
+			request.headers[IDEMPOTENCY_HEADER] = key
+			try:
+				return self._send(request, timed=timed)
+			except EastIndiaConnectionError as failed:
+				if failed.failure is not ConnectionFailure.UNREACHABLE or attempt >= self.settings.request_retries:
+					raise
+			attempt += 1
+			time.sleep(self.settings.retry_delay)
+
+	def once(self, path: str, json_body: Any) -> httpx.Response:
+		"""Sends a ``POST`` exactly once, without an ``Idempotency-Key`` and without a time limit.
+
+		A request whose body carries a password or a secret goes this way: the service stores no reply to it, and a repeat could
+		answer an elevation prompt twice.
+		"""
+		return self._send(self._build("POST", path, json_body, None, 0), timed=False)
+
+	def unkeyed(self, path: str, json_body: Any) -> httpx.Response:
+		"""Sends a ``POST`` that changes nothing, such as a screenshot, without an ``Idempotency-Key``, and gives the whole answer."""
+		return self._send(self._build("POST", path, json_body, None, 0), timed=True)
+
+	def open_stream(self, path: str) -> httpx.Response:
+		"""Sends a ``GET`` whose answer is read as it arrives, such as a followed log, with no time limit on the reading. The caller
+		closes the answer.
+		"""
+		return self._send(self._http.build_request("GET", path), timed=False, stream=True)
+
+	def lines(self, path: str) -> Iterator[str]:
+		"""Reads a streamed answer line by line, until the service ends it."""
+		response = self.open_stream(path)
+		try:
+			yield from response.iter_lines()
+		except httpx.TransportError as failed:
+			raise EastIndiaConnectionError(self.settings.address, classify(failed)) from failed
+		finally:
+			response.close()
+
+	def websocket(self, path: str, owner: ExitStack) -> ClientConnection:
+		"""Opens a route as a WebSocket, over the same mutual TLS as every other request. Closing ``owner`` closes it.
+
+		Raises:
+			EastIndiaApiError: The service refused the upgrade; the refusal's body says why.
+			EastIndiaConnectionError: No answer came.
+		"""
+		try:
+			opened = owner.enter_context(
+				connect_websocket(
+					f"wss://{self.settings.address}{path}",
+					ssl=self.settings.tls,
+					open_timeout=self.settings.request_timeout,
+					max_size=None,
+					# The client sends a ping every 20 seconds, so that a proxy does not close a connection whose program prints nothing
+					# for a while. The client never closes the connection because a ping went unanswered, because the program may still
+					# be running.
+					ping_timeout=None,
+				),
+			)
+		except InvalidStatus as refused:
+			response = refused.response
+			raise EastIndiaApiError(response.status_code, read_error(response.body or b"", response.headers.get(ERROR_HEADER))) from refused
+		except (OSError, InvalidHandshake, TimeoutError) as failed:
+			raise EastIndiaConnectionError(self.settings.address, classify(failed)) from failed
+		# websockets 15 and 16 declare the entered connection as their base type; the synchronous client always enters a
+		# ClientConnection.
+		assert isinstance(opened, ClientConnection)
+		return opened
+
+	def _build(self, method: str, path: str, json_body: Any, archive: IO[bytes] | None, start: int) -> httpx.Request:
+		if archive is not None:
+			length = archive.seek(0, 2) - start
+			headers = {"Content-Type": TAR_MEDIA_TYPE, "Content-Length": str(length)}
+			return self._http.build_request(method, path, content=_from_start(archive, start), headers=headers, timeout=self._untimed())
+		if json_body is not None:
+			content = json.dumps(json_body, separators=(",", ":")).encode()
+			return self._http.build_request(method, path, content=content, headers={"Content-Type": JSON_MEDIA_TYPE})
+		return self._http.build_request(method, path)
+
+	def _untimed(self) -> httpx.Timeout:
+		return httpx.Timeout(None, connect=self.settings.request_timeout)
+
+	def _send(self, request: httpx.Request, *, timed: bool, stream: bool = False) -> httpx.Response:
+		if not timed:
+			request.extensions["timeout"] = self._untimed().as_dict()
+		try:
+			response = self._http.send(request, stream=stream)
+		except httpx.TimeoutException as failed:
+			raise EastIndiaConnectionError(self.settings.address, ConnectionFailure.TIMED_OUT) from failed
+		except httpx.TransportError as failed:
+			raise EastIndiaConnectionError(self.settings.address, classify(failed)) from failed
+		if response.is_success:
+			return response
+		body = response.read()
+		response.close()
+		raise EastIndiaApiError(response.status_code, read_error(body, response.headers.get(ERROR_HEADER)))
+
+
+def _from_start(archive: IO[bytes], start: int) -> Iterator[bytes]:
+	archive.seek(start)
+	while chunk := archive.read(_UPLOAD_CHUNK_BYTES):
+		yield chunk

endia/_dockerignore.py

@@ -0,0 +1,282 @@
+"""The ``.dockerignore`` rules by which a build leaves files of its context folder out of the archive it sends.
+
+The rules are those the ``endia`` CLI applies, which are Docker's: each line is a pattern anchored at the context's root; a
+leading ``/`` says nothing more; ``*`` and ``?`` match within one name and never match ``/``; ``**`` matches any number of whole
+folders, or anything at the end of a pattern; ``[...]`` is a character class; a backslash makes the next character literal; a
+line starting with ``!`` takes back what earlier lines excluded; the last line that matches decides; and a path is left out when
+any folder above it is.
+
+Matching steps through the path one character at a time, keeping every place in the pattern the text so far could have reached,
+so a pattern of many ``**`` takes time in proportion to the path's length and never stalls a build.
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+IGNORE_FILE_NAME = ".dockerignore"
+# EastIndia's name for an ignore file, which a build reads in preference to a ``.dockerignore`` in the same place.
+ENDIA_IGNORE_FILE_NAME = ".endiaignore"
+
+
+class IgnoreFileError(ValueError):
+	"""An ignore file holds a pattern that is not valid. The message names the file, the line and the column of each fault."""
+
+
+@dataclass(frozen=True, slots=True)
+class _Literal:
+	character: str
+
+
+@dataclass(frozen=True, slots=True)
+class _OneCharacter:
+	"""``?``: any one character but ``/``."""
+
+
+@dataclass(frozen=True, slots=True)
+class _Characters:
+	"""``*``: any run of characters, none of them ``/``."""
+
+
+@dataclass(frozen=True, slots=True)
+class _Folders:
+	"""``**`` followed by more of the pattern: any number of whole folders, each ending in ``/``, including none."""
+
+
+@dataclass(frozen=True, slots=True)
+class _Rest:
+	"""``**`` at the end of the pattern: anything at all."""
+
+
+@dataclass(frozen=True, slots=True)
+class _Class:
+	"""``[...]``: one character among ranges, or with ``^`` one character outside them."""
+
+	ranges: tuple[tuple[str, str], ...]
+	negated: bool
+
+	def accepts(self, character: str) -> bool:
+		inside = any(low <= character <= high for low, high in self.ranges)
+		return inside != self.negated
+
+
+_Token = _Literal | _OneCharacter | _Characters | _Folders | _Rest | _Class
+
+# A place in a pattern is a pair. The first member is the index of the pattern's next piece to match. The second says whether
+# the text read so far has started the folders of a '**' at that index; once started, the match leaves those folders only at a
+# '/'.
+_Place = tuple[int, bool]
+
+
+@dataclass(frozen=True, slots=True)
+class IgnorePattern:
+	"""One line of an ignore file."""
+
+	tokens: tuple[_Token, ...]
+	reincludes: bool
+	"""Whether the line started with ``!`` and so takes back what earlier lines excluded."""
+
+	def matches(self, path: str) -> bool:
+		"""Tells whether the pattern matches the whole of a cleaned context path."""
+		places = self._closure({(0, False)})
+		for character in path:
+			places = self._closure({after for place in places for after in self._step(place, character)})
+			if not places:
+				return False
+		return (len(self.tokens), False) in places
+
+	def _step(self, place: _Place, character: str) -> list[_Place]:
+		index = place[0]
+		if index == len(self.tokens):
+			return []
+		token = self.tokens[index]
+		if isinstance(token, _Folders):
+			return [(index, True), (index + 1, False)] if character == "/" else [(index, True)]
+		if isinstance(token, (_Characters, _Rest)):
+			return [place] if isinstance(token, _Rest) or character != "/" else []
+		if isinstance(token, _Literal):
+			accepted = character == token.character
+		elif isinstance(token, _OneCharacter):
+			accepted = character != "/"
+		else:
+			accepted = token.accepts(character)
+		return [(index + 1, False)] if accepted else []
+
+	def _closure(self, places: set[_Place]) -> set[_Place]:
+		# A token that can match no text at all lets the pattern move past it without reading a character: a '*', a '**' at the
+		# end, and a '**' whose folders have not started.
+		pending = list(places)
+		reached = set(places)
+		while pending:
+			index, inside = pending.pop()
+			if index < len(self.tokens) and not inside and isinstance(self.tokens[index], (_Characters, _Folders, _Rest)):
+				after = (index + 1, False)
+				if after not in reached:
+					reached.add(after)
+					pending.append(after)
+		return reached
+
+
+def compile_pattern(pattern: str, reincludes: bool) -> IgnorePattern:
+	"""Reads a cleaned pattern, without its leading ``/`` or ``!``.
+
+	Raises:
+		ValueError: A ``[`` has no closing ``]``, or a backslash ends the pattern.
+	"""
+	tokens: list[_Token] = []
+	index = 0
+	while index < len(pattern):
+		character = pattern[index]
+		if character == "*":
+			index = _read_stars(pattern, index, tokens)
+			continue
+		if character == "[":
+			index = _read_class(pattern, index, tokens)
+			continue
+		if character == "?":
+			tokens.append(_OneCharacter())
+		elif character == "\\":
+			if index + 1 >= len(pattern):
+				raise ValueError("a trailing '\\' escapes nothing")
+			index += 1
+			tokens.append(_Literal(pattern[index]))
+		else:
+			tokens.append(_Literal(character))
+		index += 1
+	return IgnorePattern(tuple(tokens), reincludes)
+
+
+def _read_stars(pattern: str, index: int, tokens: list[_Token]) -> int:
+	# A single '*' stays within one name. A '**' also matches the '/' after it, so that 'src/**/obj' matches 'src/obj'.
+	if index + 1 >= len(pattern) or pattern[index + 1] != "*":
+		tokens.append(_Characters())
+		return index + 1
+	following = index + 2
+	if following < len(pattern) and pattern[following] == "/":
+		following += 1
+	tokens.append(_Rest() if following >= len(pattern) else _Folders())
+	return following
+
+
+def _read_class(pattern: str, index: int, tokens: list[_Token]) -> int:
+	# In a class, '^' first negates, a backslash makes the next character literal, 'a-z' is a range, and a ']' first in the class
+	# is a literal.
+	position = index + 1
+	negated = position < len(pattern) and pattern[position] == "^"
+	if negated:
+		position += 1
+	ranges: list[tuple[str, str]] = []
+	members = 0
+	range_open = False
+	while position < len(pattern) and (pattern[position] != "]" or members == 0):
+		character = pattern[position]
+		if character == "\\":
+			position += 1
+			if position >= len(pattern):
+				break
+			character = pattern[position]
+		elif character == "-" and members > 0 and position + 1 < len(pattern) and pattern[position + 1] != "]":
+			range_open = True
+			members += 1
+			position += 1
+			continue
+		if range_open:
+			ranges[-1] = (ranges[-1][0], character)
+			range_open = False
+		else:
+			ranges.append((character, character))
+		members += 1
+		position += 1
+	if position >= len(pattern):
+		raise ValueError("a '[' has no closing ']'")
+	tokens.append(_Class(tuple(ranges), negated))
+	return position + 1
+
+
+def clean(path: str) -> str:
+	"""Cleans a ``/``-separated path by its text alone: empty and ``.`` names are dropped, and ``..`` removes the name before it.
+
+	A path starting with ``/`` never climbs above its root; a relative one keeps its leading ``..`` names. An empty result is
+	``.`` for a relative path and ``/`` for a rooted one.
+	"""
+	rooted = path.startswith("/")
+	names: list[str] = []
+	for name in path.split("/"):
+		if name in ("", "."):
+			continue
+		if name == "..":
+			if names and names[-1] != "..":
+				names.pop()
+			elif not rooted:
+				names.append("..")
+			continue
+		names.append(name)
+	joined = "/".join(names)
+	if rooted:
+		return "/" + joined
+	return joined or "."
+
+
+class DockerIgnore:
+	"""The patterns of one ignore file, which decide whether a path of the context is left out."""
+
+	def __init__(self, patterns: tuple[IgnorePattern, ...] = ()) -> None:
+		self._patterns = patterns
+
+	@classmethod
+	def parse(cls, text: str, file_name: str = IGNORE_FILE_NAME) -> "DockerIgnore":
+		"""Reads an ignore file's text.
+
+		Lines end in LF or CRLF, and a leading byte-order mark is dropped. Blank lines and lines whose first non-blank character is
+		``#`` are skipped.
+
+		Raises:
+			IgnoreFileError: A line holds a pattern that is not valid, or a ``!`` with no pattern after it.
+		"""
+		patterns: list[IgnorePattern] = []
+		faults: list[str] = []
+		for number, raw in enumerate(text.removeprefix("").split("\n"), start=1):
+			line = raw.rstrip("\r")
+			trimmed = line.strip()
+			if not trimmed or trimmed.startswith("#"):
+				continue
+			column = len(line) - len(line.lstrip()) + 1
+			reincludes = trimmed.startswith("!")
+			body = trimmed[1:].strip() if reincludes else trimmed
+			if not body:
+				faults.append(f"{file_name}:{number}:{column}: A '!' needs a pattern after it.")
+				continue
+			cleaned = clean(body)
+			if len(cleaned) > 1 and cleaned.startswith("/"):
+				cleaned = cleaned[1:]
+			try:
+				patterns.append(compile_pattern(cleaned, reincludes))
+			except ValueError as problem:
+				faults.append(f"{file_name}:{number}:{column}: The pattern '{trimmed}' is not valid: {problem}.")
+		if faults:
+			raise IgnoreFileError("\n".join(faults))
+		return cls(tuple(patterns))
+
+	def is_ignored(self, path: str) -> bool:
+		"""Tells whether a context path, relative to the context's root and written with ``/``, is left out.
+
+		The patterns apply in file order, and the last one that matches the path or any folder above it decides. The context's
+		root itself is never left out.
+
+		Raises:
+			ValueError: The path points outside the context.
+		"""
+		cleaned = clean(path).lstrip("/")
+		if cleaned == ".." or cleaned.startswith("../"):
+			raise ValueError(f"The path '{path}' points outside the build context.")
+		if cleaned in ("", "."):
+			return False
+		names = cleaned.split("/")
+		folders = ["/".join(names[:count]) for count in range(1, len(names))]
+		matches: Callable[[IgnorePattern], bool] = lambda pattern: pattern.matches(cleaned) or any(map(pattern.matches, folders))
+		ignored = False
+		for pattern in self._patterns:
+			# A line that takes back can only undo a match, and an excluding line can only add one, so a line that could change
+			# nothing is skipped.
+			if pattern.reincludes == ignored and matches(pattern):
+				ignored = not pattern.reincludes
+		return ignored