evaleval 0.2.4

Signed snippets, hiccup, and a dual-eval loop. The web that should have been.

evaleval

Browser DOM is modified ONLY through javascript code snippets sent over the wire to the browers eval function. Backend actions execute ONLY through python code snippets sent over the wire to python's eval function.

The entire client is 10 lines of javascript:

import { Idiomorph } from 'idiomorph';
window.Idiomorph = Idiomorph;

const es = new EventSource('/sse');
es.addEventListener('exec', e => eval(e.data));

document.addEventListener('submit', async e => {
  e.preventDefault();
  const r = await fetch(e.target.action, { method: 'POST', body: new FormData(e.target) });
  const t = await r.text();
  if (t) eval(t);
});

Three endpoints. No framework.

GET  /       — serve the shell, which is just a script tag with the above js snippet.
GET  /sse    — push js snippets to the browser, if your app has a push path.
POST /     — verify, eval in python, return js code to be eval'd

Example: evaleval-todo

evaleval also includes a quick implementation of clojure's hiccup, a data-driven embedded DSL for rendering DOM nodes in an ergonomic way.

Observe this example:

from evaleval import Signer, Three, Two, Selector, MORPH, APPEND, REMOVE

signer = Signer()

def add_form():
    return ["form", {"action": "/", "method": "post"},
        *signer.snippet_hidden("add($new-todo-body)"),
        ["input", {"type": "text", "name": "new-todo-body", "placeholder": "what needs doing?"}],
        ["button", {"type": "submit"}, "add"],
    ]

All forms have a handler. In a traditional stack, it would be pointed to by a url which points to a routing table which points to a handler function. In evaleval, the handler is embedded into the form itself.

The add($new-todo-body) is sent directly to python's eval with $new-todo-body sent through python's repr and spliced into the python source string. The source string must be an expression not a statement, as it must have a return value. Because as you'll see later, the result of eval is returned directly to the client.

So the handler function from the form is called directly with form arguments. And it returns javscript code. Now how do you write js snippets ergonomically in python? You could write them directly:

def add(text):
    t = {"id": uuid.uuid4().hex[:8], "text": text, "done": False}
    TODOS.append(t)
    escaped = t["text"].replace("`", "\\`")
    return PlainTextResponse(f"""
Idiomorph.morph(document.querySelector('#add-form'), `<form id="add-form">...</form>`);
document.querySelector('#todo-list').insertAdjacentHTML('beforeend', `<li id="todo-{t["id"]}">{escaped}</li>`);
Idiomorph.morph(document.querySelector('p.count'), `<p class="count">...</p>`);
console.log('todo added', {text!r});
""")

Ew.

However, I have instead built an embedded data-driven DSL much like specter, which lets you construct js snippets in fluent python. The number we are indexing into is the arity of how deep we can index into until it executes the path, rendering it into a js string. The details of this process are fairly simple and are described here. The indexable arity objects are also just very cool.

The most common arity path pattern is Three[dom selector][action][hiccup data].

def add(text):
    t = {"id": uuid.uuid4().hex[:8], "text": text, "done": False}
    TODOS.append(t)
    return PlainTextResponse(";".join([
        Three[Selector("#add-form")][MORPH][add_form()],
        Three[Selector("#todo-list")][APPEND][todo_item(t)],
        Three[Selector("p.count")][MORPH][remaining_count()],
        f"console.log('todo added', {text})"
    ]))

def delete(todo_id):
    TODOS.remove(_find(todo_id))
    return PlainTextResponse(";".join([
        Two[Selector(f"#todo-{todo_id}")][REMOVE],
        Three[Selector("p.count")][MORPH][remaining_count()],
    ]))

These js snippets go directly into the browser's eval function, so you can do whatever you want.

Two[Selector("#progress-bar")][Eval(f"=> $.width = '{width}%'")]

Security

from evaleval import SnippetExecutionError

@app.post("/")
async def do(request):
    form = await request.form()
    try:
        snippet = signer.verify_snippet(form)
        return eval(snippet)

    except SnippetExecutionError as e:
        return PlainTextResponse(e.message, status_code=e.status_code)

Verify snippet consumes the nonce, so for each GET you can only press each button once. Verify snippet checks the HMAC against the provided snippet, restricting code running on the server to be only code that the server itself produces. So if a user can't do an action, don't sign a snippet with that action for them.

Notice this line in the todo submit form handler:

Three[Selector("#add-form")][MORPH][add_form()],

This is neceseary. Because each action is only allowed exactly once per GET. But you don't want to have to reGET the page to send another todo. So a new nonce is required to be generated by add_form(), which returns hiccup, which is rendered to an htmlstring, which is morphed into the dom at #add-form.

Each snippet is not only a continuation, but also a capability ticket.

uv install evaleval