subroutine 0.1.0__py3-none-any.whl

subroutine/__init__.py

@@ -0,0 +1,25 @@
+"""Subroutine — project management for people and agents, in equal measure.
+
+A self-hostable task and project tracker whose HTTP API, CLI and data model treat a
+person and an AI agent as equally first-class users. See ``SPEC.md`` for the full
+specification and ``MVP-PLAN.md`` for what is being built first.
+"""
+
+import importlib.metadata
+
+
+def _installed_version () -> str:
+	"""Report the installed package version, or a placeholder when running from source."""
+
+	try:
+		return importlib.metadata.version("subroutine")
+
+	except importlib.metadata.PackageNotFoundError:
+		return "0.0.0+unknown"
+
+
+__version__ = _installed_version()
+
+#: The API version exposed at ``/v1`` and reported in ``X-Subroutine-Api-Version``.
+#: This tracks the wire contract, not the package release.
+API_VERSION = "1.0"

subroutine/__main__.py

@@ -0,0 +1,12 @@
+"""``python -m subroutine`` — the same command as the ``subroutine`` script.
+
+Worth having for two reasons beyond tidiness. A virtualenv whose ``bin`` is not on the path
+still has a working command, which is the situation in a container more often than not; and a
+test that needs a *separate process* — one serving over a real socket — can start one without
+knowing where the console script was installed.
+"""
+
+import subroutine.cli.main
+
+if __name__ == "__main__":
+	subroutine.cli.main.main()

subroutine/addressing.py

@@ -0,0 +1,49 @@
+"""What may be used as an identifier inside an address.
+
+A project key becomes a path segment — ``/v1/projects/SR`` — and so does a task ref. Some
+segments are already spoken for by an endpoint: ``/v1/tasks/search`` is the search
+endpoint, not a task called ``search``. Anything that would land on one of those is
+refused when it is created, because the alternative is a project that exists, is listed,
+and cannot be opened (SPEC.md §8.1).
+
+Deliberately free of any HTTP framework. The rule is enforced in the service layer, which
+runs for the CLI as well, and a domain module reaching into the API package to find out
+what a valid key is would have the dependency exactly the wrong way round.
+"""
+
+#: Words a literal route already claims in the task and project path spaces. Listed here
+#: rather than derived from the routing table, because a key is refused at creation —
+#: possibly by a CLI with no application built — and because the list is a promise about
+#: future endpoints too: ``sync`` has no route yet, and reserving it now costs nothing
+#: while un-reserving it later would cost somebody their project key.
+RESERVED_PATH_WORDS = frozenset({"batch", "next", "parse", "search", "sync"})
+
+
+#: Words a *workspace* short name may not take, because a workspace slug became part of an
+#: address in §13.7 — ``connection/workspace/ref``. Position tells a connection from a
+#: workspace, so there is no structural ambiguity; what these prevent is the human kind. A
+#: workspace called ``local`` beside the implicit ``local`` connection makes ``use local``
+#: mean two things, and ``all``/``none``/``me`` read as instructions rather than places.
+#:
+#: Reserved now rather than later, on the same reasoning as :data:`RESERVED_PATH_WORDS`:
+#: reserving costs nothing today and un-reserving would cost somebody their workspace name.
+RESERVED_WORKSPACE_WORDS = frozenset(
+	{"all", "default", "here", "local", "me", "mine", "none", "self"}
+)
+
+
+def is_reserved_workspace_word (value: str) -> bool:
+	"""Report whether a workspace short name would be confusing as an address segment."""
+
+	return value.strip().lower() in RESERVED_WORKSPACE_WORDS
+
+
+def is_reserved_word (value: str) -> bool:
+	"""Report whether a value would be swallowed by a literal route.
+
+	Compared case-insensitively. Identifiers in a path resolve case-insensitively
+	(SPEC.md §8.1), so a project keyed ``SEARCH`` is reachable at the same address as the
+	search endpoint whether or not the letters match.
+	"""
+
+	return value.strip().lower() in RESERVED_PATH_WORDS

subroutine/api/__init__.py

@@ -0,0 +1,11 @@
+"""The HTTP API.
+
+Thin by design. Every rule about what may happen lives in ``subroutine.domain``, so that
+the CLI and the API cannot come to different conclusions about the same request — the
+routers translate between HTTP and the service layer and do nothing else (SPEC.md §8.1).
+
+The application is built by a factory rather than created at import time. A module-level
+application would open the user's real database as a side effect of importing this
+package, which makes it impossible to test against a temporary one and surprising to
+import for any other reason.
+"""

subroutine/api/admin.py

@@ -0,0 +1,117 @@
+"""Operational endpoints for whoever runs the instance (SPEC.md §12.6).
+
+**Backup is here and restore deliberately is not.** An agent about to attempt something bulk
+should be able to snapshot first, which is why taking a backup is reachable over HTTP. Putting
+one back replaces the database the serving process currently has open — an endpoint that pulls
+the floor out from under its own request is not a feature, and §12.4's recovery property
+depends on the administrative commands working when the service will *not* start. Restore is
+``subroutine db restore``, and only that.
+
+Both endpoints require ``instance:admin``, which no role may carry: it is held only by a
+superuser, and a token still narrows it (§7.3).
+"""
+
+import datetime
+
+import fastapi
+import pydantic
+import sqlalchemy.orm
+
+import subroutine.api.dependencies
+import subroutine.api.routing
+import subroutine.api.security
+import subroutine.db.backup
+import subroutine.domain.authorization
+import subroutine.permissions
+
+router = fastapi.APIRouter(
+	prefix="/v1/admin",
+	tags=["admin"],
+	route_class=subroutine.api.routing.Transactional,
+)
+
+
+class Backup(pydantic.BaseModel):
+	"""One copy of the database, described well enough to choose between several."""
+
+	name: str
+	path: str
+	taken_at: datetime.datetime
+	schema_head: str
+	size_bytes: int
+
+	#: Null for the default instance, which has no profile name (SPEC.md §12.5).
+	profile: str | None
+
+
+class Backups(pydantic.BaseModel):
+	"""Every backup this instance holds, newest first."""
+
+	items: list[Backup]
+
+
+def _rendered (backup: subroutine.db.backup.Backup) -> Backup:
+	"""Describe a backup for a caller, with the path as text rather than a ``Path``."""
+
+	return Backup(
+		name=backup.name,
+		path=str(backup.path),
+		taken_at=backup.taken_at,
+		schema_head=backup.schema_head,
+		size_bytes=backup.size_bytes,
+		profile=backup.profile,
+	)
+
+
+@router.post("/backups", response_model=Backup, status_code=201)
+def create_backup (
+	actor: subroutine.api.security.PrincipalDep,
+	settings: subroutine.api.dependencies.SettingsDep,
+	session: subroutine.api.dependencies.SessionDep,
+	keep: int | None = fastapi.Body(
+		None,
+		embed=True,
+		description="Afterwards, keep only this many of the newest backups.",
+	),
+) -> Backup:
+	"""Take a datetime-stamped copy of the database and report where it went."""
+
+	subroutine.domain.authorization.authorize_instance(
+		actor, subroutine.permissions.INSTANCE_ADMIN
+	)
+
+	return _rendered(subroutine.db.backup.take(_engine_behind(session), settings, keep=keep))
+
+
+def _engine_behind (session: sqlalchemy.orm.Session) -> sqlalchemy.engine.Engine:
+	"""Return the engine this session ultimately talks through.
+
+	The engine behind the *session*, rather than a second one built from the configured URL: a
+	backup taken over a different connection than the application serves from is a backup of a
+	database that may not be the one being served.
+
+	``get_bind`` answers with an ``Engine`` normally and with a ``Connection`` when something
+	has bound one — which the test harness does, so that a request shares the test's
+	transaction. Both have an engine behind them and it is the same engine either way.
+	"""
+
+	bind = session.get_bind()
+
+	if isinstance(bind, sqlalchemy.engine.Connection):
+		return bind.engine
+
+	return bind
+
+
+@router.get("/backups", response_model=Backups)
+def list_backups (
+	actor: subroutine.api.security.PrincipalDep,
+	settings: subroutine.api.dependencies.SettingsDep,
+) -> Backups:
+	"""List the backups this instance holds, newest first."""
+
+	subroutine.domain.authorization.authorize_instance(
+		actor, subroutine.permissions.INSTANCE_ADMIN
+	)
+
+	return Backups(items=[_rendered(found) for found in subroutine.db.backup.catalogue(settings)])

subroutine/api/agenda.py

@@ -0,0 +1,115 @@
+"""``GET /v1/agenda`` — "what am I doing today?" as one request.
+
+The four buckets are §8.6's, and they are **disjoint by priority**: a task appears in
+exactly one of them, so a client can render the whole thing without deduplicating and a
+count means what it says. Overdue wins over today, today over upcoming, and anything with
+no date at all falls to unscheduled.
+
+Unlike ``GET /v1/tasks`` this spans every workspace the caller can read, because "what am I
+doing today" is a question about a person's day rather than about a workspace — the dentist
+appointment and the deployment are both in it (SPEC.md §13.7).
+"""
+
+import datetime
+import uuid
+
+import fastapi
+import sqlalchemy.orm
+
+import subroutine.api.dependencies
+import subroutine.api.query
+import subroutine.api.routing
+import subroutine.api.security
+import subroutine.db.types
+import subroutine.domain.agenda
+import subroutine.domain.authentication
+import subroutine.domain.instances
+import subroutine.domain.schedule
+import subroutine.domain.selection
+import subroutine.domain.workspaces
+import subroutine.views
+
+router = fastapi.APIRouter(
+	prefix="/v1",
+	tags=["agenda"],
+	route_class=subroutine.api.routing.Transactional,
+)
+
+
+@router.get(
+	"/agenda",
+	summary="What am I doing today?",
+	dependencies=[subroutine.api.query.UnknownQueryDep],
+)
+def read (
+	actor: subroutine.api.security.PrincipalDep,
+	session: subroutine.api.dependencies.SessionDep,
+	date: datetime.date | None = fastapi.Query(
+		None, description="The day to build the agenda for. Defaults to today, in your zone."
+	),
+	timezone: str | None = fastapi.Query(
+		None, description="Interpret the day in this zone, overriding your own."
+	),
+	horizon_days: int | None = fastapi.Query(
+		None, ge=1, description="How far ahead 'upcoming' reaches."
+	),
+	unscheduled_limit: int = fastapi.Query(
+		subroutine.domain.agenda.DEFAULT_UNSCHEDULED_LIMIT,
+		ge=0,
+		description="How many undated tasks to list. The total is always reported.",
+	),
+	workspace_id: str | None = fastapi.Query(
+		None,
+		description="Narrow to one workspace, by id or short name. Defaults to all of them.",
+	),
+) -> subroutine.views.Agenda:
+	"""Return today's work, in four disjoint buckets."""
+
+	now = subroutine.db.types.utcnow()
+	zone = subroutine.domain.schedule.zone_for(
+		user=actor.user,
+		instance=subroutine.domain.instances.get(session),
+		explicit=timezone,
+	)
+
+	built = subroutine.domain.agenda.build(
+		session,
+		principal=actor,
+		workspace_ids=_scope(session, actor, workspace_id),
+		now=now,
+		timezone=zone,
+		date=date,
+		horizon_days=horizon_days,
+		unscheduled_limit=unscheduled_limit,
+	)
+
+	return subroutine.views.agenda(session, built)
+
+
+def _scope (
+	session: sqlalchemy.orm.Session,
+	actor: subroutine.domain.authentication.Principal,
+	wanted: str | None,
+) -> list[uuid.UUID]:
+	"""Return the workspaces this agenda covers: one if asked for, otherwise all readable.
+
+	**Spanning everything is the default and stays the default** — "what am I doing today" is a
+	question about a person's day, and an agenda that silently covered one workspace would hide
+	the dentist behind a work backlog.
+
+	The filter exists because the reverse also bites: one instance holding a personal to-do list
+	*and* a project's backlog put seven undated project tasks above "buy salad" the first time
+	this project used itself. Every other listing already took ``workspace_id``; the agenda was
+	the only one that did not, so this is a consistency repair as much as a feature.
+
+	Resolved through ``selection.workspace`` like every other listing, so a short name works, a
+	token's pin still applies, and a workspace the caller cannot read reads as absent rather than
+	forbidden (§7.3a).
+	"""
+
+	if wanted is not None:
+		return [subroutine.domain.selection.workspace(session, actor, requested=wanted).id]
+
+	return [
+		workspace.id for workspace in subroutine.domain.workspaces.readable(session, actor)
+	]

subroutine/api/app.py

@@ -0,0 +1,171 @@
+"""Building the application.
+
+A factory, not a module-level application: importing this package should not open the
+user's database, and a test needs an instance pointed at a temporary one. ``subroutine
+serve`` and any ASGI server call :func:`create_app`.
+
+The order of what happens here is load-bearing and is set out in :func:`create_app`.
+"""
+
+import contextlib
+import typing
+
+import fastapi
+import fastapi.middleware.cors
+import sqlalchemy.engine
+import sqlalchemy.orm
+
+import subroutine
+import subroutine.api.admin
+import subroutine.api.agenda
+import subroutine.api.comments
+import subroutine.api.documents
+import subroutine.api.events
+import subroutine.api.health
+import subroutine.api.identity
+import subroutine.api.meta
+import subroutine.api.middleware
+import subroutine.api.problems
+import subroutine.api.projects
+import subroutine.api.routing
+import subroutine.api.tasks
+import subroutine.api.tokens
+import subroutine.api.users
+import subroutine.api.workspaces
+import subroutine.config
+import subroutine.db.migrate
+import subroutine.db.session
+
+#: Shown at ``/docs`` and in the generated OpenAPI document. The audience is a developer
+#: or an agent deciding whether this endpoint does what they need, so it points at the two
+#: places that answer that rather than describing the product again.
+DESCRIPTION = """
+Project management for people and agents, in equal measure.
+
+`GET /v1/meta` reports this installation's vocabulary — its statuses, link types, field
+operators and date grammar — so a client can read them rather than assume them.
+`GET /v1/docs/agent` is a guide written for an agent working through this API.
+
+Errors are RFC 9457 problem documents and every one carries a stable `code`; the codes are
+part of the public contract and are listed in `docs/errors.md`.
+""".strip()
+
+#: Every router, in the order they are registered — and that order is load-bearing, which
+#: is why they are declared as data rather than as a run of ``include_router`` calls. A
+#: router carrying literal sub-paths must come before one carrying ``{id_or_ref}`` in the
+#: same space, and :func:`subroutine.api.routing.check` reads this list to enforce it.
+ROUTERS: tuple[subroutine.api.routing.Mounting, ...] = (
+	("", subroutine.api.health.router),
+	("", subroutine.api.identity.router),
+	("", subroutine.api.workspaces.router),
+	("", subroutine.api.users.router),
+	("", subroutine.api.tokens.router),
+	("", subroutine.api.meta.router),
+	("", subroutine.api.agenda.router),
+	("", subroutine.api.tasks.router),
+	# The link sub-resources come after the routers whose paths they extend. They cannot
+	# shadow or be shadowed — `/{id_or_ref}/links` is longer than anything in either — but
+	# `routing.check` is what says so rather than anybody's reading of it.
+	("", subroutine.api.documents.task_links),
+	("", subroutine.api.projects.router),
+	("", subroutine.api.documents.router),
+	("", subroutine.api.documents.document_links),
+	# The comment sub-resources come after the routers whose paths they extend, like links.
+	("", subroutine.api.comments.task_comments),
+	("", subroutine.api.comments.project_comments),
+	("", subroutine.api.comments.document_comments),
+	("", subroutine.api.comments.router),
+	# The history sub-resources, likewise after the routers they extend.
+	("", subroutine.api.events.task_events),
+	("", subroutine.api.events.project_events),
+	("", subroutine.api.events.document_events),
+	("", subroutine.api.admin.router),
+)
+
+
+def create_app (
+	*,
+	settings: subroutine.config.Settings | None = None,
+	session_factory: sqlalchemy.orm.sessionmaker[sqlalchemy.orm.Session] | None = None,
+) -> fastapi.FastAPI:
+	"""Build the application.
+
+	``session_factory`` is for tests, which supply one bound to a transaction they can roll
+	back. When it is not given the engine is built here from ``settings`` and disposed when
+	the application shuts down.
+	"""
+
+	resolved = settings or subroutine.config.load_settings()
+
+	application = fastapi.FastAPI(
+		title="Subroutine",
+		summary="Project management for people and agents, in equal measure.",
+		description=DESCRIPTION,
+		version=subroutine.API_VERSION,
+		openapi_url="/v1/openapi.json",
+		docs_url="/docs",
+		redoc_url="/redoc",
+		lifespan=_lifespan,
+	)
+
+	application.state.settings = resolved
+	application.state.engine = None
+	application.state.session_factory = session_factory
+
+	# Read once. It comes from the migration scripts shipped in this package, which cannot
+	# change while the process runs, and the readiness check should not walk a directory
+	# every time a load balancer asks whether it is alive.
+	application.state.schema_head = subroutine.db.migrate.head_revision()
+
+	if session_factory is None:
+		engine = subroutine.db.session.create_engine(resolved.database_url)
+
+		application.state.engine = engine
+		application.state.session_factory = subroutine.db.session.create_session_factory(engine)
+
+	application.middleware("http")(subroutine.api.middleware.correlate)
+
+	if resolved.cors_origins:
+		# Only when configured. A browser is not the primary client here, and a default
+		# that allows credentialed cross-origin requests is a hole nobody asked for.
+		application.add_middleware(
+			fastapi.middleware.cors.CORSMiddleware,
+			allow_origins=resolved.cors_origins,
+			allow_credentials=True,
+			allow_methods=["*"],
+			allow_headers=["*"],
+			expose_headers=[
+				subroutine.api.middleware.REQUEST_ID_HEADER,
+				subroutine.api.middleware.API_VERSION_HEADER,
+			],
+		)
+
+	subroutine.api.problems.install(application)
+
+	# Checked before anything is mounted, so a violation is a refusal to build rather than
+	# an application that starts with an endpoint nobody can reach (SPEC.md §8.1).
+	subroutine.api.routing.check(ROUTERS)
+
+	for prefix, router in ROUTERS:
+		application.include_router(router, prefix=prefix)
+
+	return application
+
+
+@contextlib.asynccontextmanager
+async def _lifespan (application: fastapi.FastAPI) -> typing.AsyncIterator[None]:
+	"""Hold the application's own resources for as long as it is serving.
+
+	Only an engine this module built is disposed. A session factory handed in by a test
+	belongs to the test, and disposing its engine underneath it would break the fixture
+	that owns it.
+	"""
+
+	try:
+		yield
+
+	finally:
+		engine = application.state.engine
+
+		if isinstance(engine, sqlalchemy.engine.Engine):
+			engine.dispose()