API

Every function this app publishes over HTTP, and what each one checks before it
does anything.

Who this is for. Somebody calling BenchPress from another program, or adding
an endpoint and wondering what the house rule is.

Before you start. Read How an endpoint is guarded.
The decorator publishes a function. It grants nothing. Every entry in the tables
below names its own check, because there is no check anywhere else.

Calling convention

Every endpoint is a Frappe whitelisted method. Call it by dotted path.

curl -s https://<host>/api/method/benchpress.api.get_labs \
  -H "Cookie: sid=<session id>"

Arguments go as query parameters on a GET or as form fields on a POST.
Frappe decides the method from the function, not from a route table.

Thirty-five of the fifty are in benchpress.api. Four more are module functions
elsewhere. The remaining eleven are document methods, called through
run_doc_method rather than by path. All three kinds are marked below.

How an endpoint is guarded

Five helpers in benchpress/permissions.py do the work. An endpoint calls one
of them as its first statement.

require_bench_access calls frappe.has_permission on the document itself. It
scopes because the BenchPress User permission row on Bench Instance carries
if_owner: 1. See How a row is scoped.

A second gate sits above some endpoints. requires_admission is a decorator in
benchpress/credits/guard.py. It refuses an action before any work is queued,
and it does nothing at all while enable_credits is 0.

Two endpoints answer a guest. They are listed separately in
The two guest endpoints, and both are rate limited.

Labs and templates

build_lab_image and build_lab_golden queue work and return at once. Watch
the Build Log for the result.

get_lab_form_options is admin-only because only an admin reaches the New lab
screen. Do not read it as a public enum list.

Benches

bench_action takes four actions: start, restart, stop and delete.

start, restart and stop all refuse an instance with no container. A Draft
bench has never been deployed, and a reaped one has had its container removed.

create_bench is idempotent for a pair of caller and lab. The bench name is an
MD5 of the two, so a second call redeploys rather than making a second bench.

server_time exists so a countdown in the browser corrects against the server
clock instead of the laptop's.

History

The two history endpoints do not check permissions in api.py. They delegate
immediately to benchpress/run_history.py, and the check is the first statement
there. This is the one place where the guard is a function call away, so the
table names where it lives.

Both are endpoints rather than a generic list read for a reason.
Build Log had no query condition, and reading it through the generic list API
served every user's image builds to everybody. Scoping cannot be added to a
generic read, so it is applied here: deploy rows go through frappe.get_list
and pick up deploy_log_query_conditions, and build rows are filtered by owner
for anybody who is not an admin.

Both answers carry window_days, limit and truncated. Logs are cleared
after seven days, so neither table is complete, and the answer says so rather
than implying otherwise.

Devices

Every device endpoint is a wrapper over vpn_management. A device is a
VPN Peer, not a BenchPress DocType.

get_device_types exists so no screen hand-types the list.
run_connection_test tests the caller's peer and never the shared
infrastructure.

Credentials

Three endpoints return secrets. All three take a bench name and check access to
that bench.

These exist because Frappe does not return Password fields in an ordinary
document read. Reading the Bench Instance gives you nothing. Ask here.

Credits

Every endpoint below works while enable_credits is 0. They report that
credits are off rather than failing.

get_user_context is the one endpoint with no raising guard, and that is
deliberate. It answers what the session already knows about itself. It calls
frappe.get_roles and is_admin, and it returns no other user's data.

get_credit_statement filters on the session, never on an argument. There is no
way to ask for another user's ledger.

renew_bench takes a request_id. A retried call carrying the same id does not
charge twice. The new deadline extends from the deadline the caller already had,
not from now.

buy_credits prices from the pack, never from the caller. See
Credits and billing for the gateway.

Screens

Diagnostics

run_diagnostics reads. preflight_runtime creates a container, which is why
it is separate and why it is admin-only. Neither reads the queue workers. See
Diagnostics.

Document methods

Eleven whitelisted methods live on controllers rather than in api.py. Frappe
calls them through run_doc_method, and it checks the document's own permission
before the method runs.

Bench Instance

Four methods, used from the Desk form. None calls a permission helper. The
document check plus if_owner on the BenchPress User role is the guard.

enqueue_deploy and enqueue_redeploy deduplicate on a job id of
deploy_bench:<name>. A second click while a deploy runs says so and queues
nothing.

Database Server

Five methods. Each one calls self.has_permission and throws, so the check is
explicit here rather than inherited.

Credit Account

Two methods, both admin-only.

post_adjustment is how a balance is set without a payment. It is the path the
documentation screenshots used, because the gateway keys are empty on this host.

The two guest endpoints

Two functions carry allow_guest=True. They are the whole surface an
unauthenticated caller can reach, and both are rate limited to the same shape.

waitlist.join always answers the same way. A caller cannot tell a new address
from one already on the list, so the endpoint is not an account oracle.

signup.sign_up answers exactly as Frappe's own signup does, behind two gates
from Credit Settings. Both gates are off on a self-hosted install. See
Self-serve signup.

Two more waitlist functions are admin-only and not guest-reachable.

The whole list, counted

Fifty @frappe.whitelist() functions. Every one is in a table above.

Recount after a change:

grep -rn "@frappe.whitelist" --include=*.py benchpress/ | wc -l

Adding an endpoint

1. Write the function in the module that owns the concern, not in api.py.
2. Add a thin wrapper in api.py that calls a permission helper first.
3. If the action costs credits or hits a cap, add requires_admission under
   @frappe.whitelist().
4. Query with frappe.qb. A raw frappe.db.sql string is a lint failure.
5. Add the endpoint to the table on this page.

The decorator order matters. @frappe.whitelist() goes on top, and
@requires_admission(...) below it, so the gate runs inside the published
function.

Verify

Confirm an endpoint refuses the caller it should refuse:

bench --site <site> run-tests --app benchpress --module benchpress.tests.test_api_authorization

Troubleshooting

Related

• Data model — the rows these endpoints read.
• Deploy pipeline — what create_bench sets running.
• Production safety — the endpoint-by-endpoint audit of these guards.
• Realtime — how a screen hears about the result.