morca

morca · API · web

orca.web.router

The router: a table of routes, each a method, a path pattern, what kind of request it is and the handler that answers it. orca.web.routes is the table; orca.web.server looks a request up here and wraps the handler in what its kind needs.

A pattern is the path's segments: a literal (runs), a parameter ({name}: any segment but an empty one, URL-decoded) or a number ({id:int}). A path matches a route of its length whose literals are its segments and whose numbers parse. A path that would match but for a number that isn't one (/runs/x, /runs/1/attempts/x/log) is answered 404, "no run x", from the route's noun.

A GET route answers HEAD too. A read (GET) that matches nothing is 404, "nothing at <path>"; a POST that matches nothing is 405, since only the actions take one, unless it's an action's but for its number, which is 404.

Structs

Call

struct Call

A request as its handler sees it: where it went, the route's parameters, its form and who sent it.

Implements Movable

Fields
url: String: The path and its query, as asked.
path: String
params: Dict[String, String]
form: String: A POST's fields, application/x-www-form-urlencoded (a JSON body is converted, orca.web.auth.json_form).
body: String: The body as it was sent.
user: String: Who's logged in (a session or an API token), or empty (orca.web.auth.sign_in).
source: String: How they're logged in: "ui" (a session) or "cli" (an API token).
bearer: String: The API token it was sent with, or empty.
session: String: The session cookie it was sent with, or empty.
address: String: The address it came from (orca.web.auth.client).

__init__

def __init__(out self, url: String, path: String)

query

def query(self, name: StringSpan) -> String

A query parameter's value, decoded, or empty.

field

def field(self, name: StringSpan) -> String

A field of the form, decoded, or empty.

param

def param(self, name: String) -> String

A {name} of the route's pattern, decoded.

int

def int(self, name: String) -> Int

A {name:int} of the route's pattern.

Route

struct Route

Implements Copyable, Movable

Fields
methods: Int: GET, POST or both (GET | POST).
pattern: StaticString
kind: Int: PAGE, ACTION or AUTH.
handler: def(mut State, Call) raises thin -> Page
noun: StaticString: What the pattern's number names, for the 404 of one that isn't: "run" answers "no run x".

Found

struct Found

The route a request matched, with its parameters; or, without one, the 404 of a number that isn't one (miss), or nothing.

Implements Movable

Fields
route: Optional[Route]
params: Dict[String, String]
miss: String

__init__

def __init__(out self)

Functions

page

def page(pattern: StringSpan[ImmStaticOrigin], handler: def(mut State, Call) raises thin -> Page, noun: StringSpan[ImmStaticOrigin] = StringSpan("")) -> Route

A read at pattern.

action

def action(pattern: StringSpan[ImmStaticOrigin], handler: def(mut State, Call) raises thin -> Page, noun: StringSpan[ImmStaticOrigin] = StringSpan("")) -> Route

A POST at pattern that changes something.

auth

def auth(pattern: StringSpan[ImmStaticOrigin], handler: def(mut State, Call) raises thin -> Page) -> Route

Logging in or out at pattern, by GET or POST.

find

def find(routes: List[Route], method: String, path: String) -> Found

The first route of routes for method that path matches.

answer

def answer(routes: List[Route], mut db: State, var call: Call, kind: Int) -> Optional[Page]

What the PAGE or ACTION route call.path names answers, for orca commands over the database (orca.web.server.read_page, act): for no such page a 404, and for no such action None.

Aliases

comptime GET = 1

GET, and HEAD with it.

comptime POST = 2
comptime PAGE = 0

A read: the page, its JSON or a fragment of it. Its header says who's logged in.

comptime ACTION = 1

A POST that changes something (orca.api.actions): it needs a session once login is on, and is audited as its user's.

comptime AUTH = 2

Logging in and out (orca.web.auth), answered as the handler says.

comptime Endpoint = def(mut State, Call) raises thin -> Page

What answers a route: a page, its JSON and where to go, as Page.