Skip to content
HappyView

Libraries

A library is a plugin a script loads with require. Each has a namespace under happyview., declares the capabilities it needs, and documents its own surface in its README. HappyView ships none of them: every library is installed from the plugins repository through Integrations > Plugins or the admin API, and a script that requires one that is not installed fails to load.

requireCapabilitiesPurposeSurface
happyview.dbrecords:readRead indexed records: a chainable query per collection, one record by URI, substring search, and the backend nameREADME
happyview.sqldatabase:read, database:writeRaw SQL, and a chainable builder over the operator’s own tablesREADME
happyview.backlinksrecords:readRecords whose strong refs point at a given AT URIREADME
happyview.recordcaller:write, records:read, records:writeRecord writes as the calling user, blob uploads, direct local-index writes, and lexicon validationREADME
happyview.xrpccaller:read, caller:callXRPC queries and procedures as the calling userREADME
happyview.atprotoatproto:read, attest:signService resolution, blob download, label lookup, and attestation signing and verificationREADME
happyview.spacesspaces:read, spaces:writePermissioned spaces: records, membership and invitesREADME
happyview.linked_reposlinked_repos:useRecord writes, blob uploads and XRPC calls through repos an admin has linkedREADME
happyview.jobsjobs:create, jobs:read, jobs:read_anyEnqueue background jobs, and read them back (reading needs happyview-jobs 1.1.0 or later)README
happyview.httpnetwork:request:unrestrictedOutbound HTTP: get, post, put, patch, delete, headREADME
happyview.blobsblobs:read, blobs:writeStore and read byte content, addressed by the CID of its contentsREADME
happyview.accountcaller:emailThe calling user’s email address, as their PDS reports itREADME

The capability column is what an operator grants when installing the library, and it bounds what any script can do through it: happyview.sql with database:write can run any statement, happyview.xrpc with caller:call can invoke any procedure as the user. Install only what your scripts use.

Conventions every library follows

Section titled “Conventions every library follows”

Envelopes. Every read of an indexed record answers an envelope rather than the bare body:

{ uri, did, collection, rkey, cid, indexed_at, record }

record is the stored body verbatim. cid is nil for a row written only with save_local, and indexed_at is nil until the network has echoed the record; a write through happyview.record is in the index at once, with the PDS’s cid. A page is { records, cursor }, where cursor is an opaque string present only when more records exist.

Chains. A constructor such as db.records(collection) or backlinks.to(uri) returns an object whose lazy steps (where, sort, limit, cursor, did, collection) each return the same object, so they chain, and whose immediate calls (run, count, first) make the library call. A lazy step given nil is skipped, so :limit(input.limit) reads as no limit when the input has none. An object holds nothing between calls, so a library cannot keep a transaction open, and a script cannot hand a library a function.

Acting as the caller. A library acts as ctx.caller_did, and a call that needs the caller’s PDS session succeeds only when ctx.has_pds_auth is true. happyview.linked_repos is the exception: it acts as the linked repo, from any script kind, and the grant’s scopes bound it instead.

Errors. A library failure raises a Lua error prefixed with the library and function, happyview-db.get: …, carrying the error code the README lists (BAD_INPUT, NO_SESSION, PDS_ERROR, …). Catch one with pcall when the failure is expected.

Protected tables. happyview.sql runs against the same database as the index, so raw and from are refused on HappyView’s internal happyview_* tables other than the public AppView data. The allowlist is in Developing Plugins. To read one collection quickly, use the view described in Reading one collection.

Record views on a raw read route. When an instance’s record storage offers a raw read route, raw reads of happyview_records and happyview_record_refs, and from on either view, run on that route in its own SQL dialect, which db.backend() doesn’t report. A query that reads those views together with other tables is refused, and a routed read fails with STORAGE_UNAVAILABLE while the storage is down. Raw SQL on the record views has the details.

Next steps

Section titled “Next steps”