README
¶
arandu-io/framework
Application bootstrap, typed configuration, and the authorization every repository call goes through.
About Arandu
Note: this repository holds the core of the framework. To build an application with it, run
aru new <name>, or start from arandu-io/arandu.
Arandu is a Go framework for web applications, services and APIs, built around
three things, in this order: development speed — a small, predictable
surface, and a generator that emits a full module (screens, migration, policy)
in one shot; performance — a single compiled binary, HTML over HTMX instead
of a JavaScript bundle, so there is no template runtime, no hydration step and
no Node in the request path; and authorization the compiler charges for — a
Grant has only unexported fields, and reaching the database without one does
not compile.
What it delivers
- Authorization that cannot be skipped —
Grantcannot be built by writing a struct literal outside the package that issues it, and every repository signature requires one before the id.TestRepositoryWithoutGrantDoesNotCompileproves it by running the compiler over two fixtures and requiring the exact failure:not enough arguments in call to repo.Findfor a call with no Grant,cannot refer to unexported field validfor one that tries to forge one. - Tenant scoped at the source — the tenant is read from the Grant with
Tenant(g), never from a path, a body, a query or a header, andValidTenantrefuses anything outside^[a-z0-9][a-z0-9_-]{0,63}$. - One boot sequence —
foundationcomposes the process exactly once, at start, never per request. - Background work that survives a crash — jobs carry a Grant, domain
events are written to an outbox in the same transaction as the row that
caused them, and a task the scheduler marks
Singletontakes a named lock, so N copies of the process do not run it N times. - Diagnosis without an extra install — a console, a request timeline and an N+1 detector live in the core rather than a plugin, and allocate nothing when they are off.
Be honest about the limit: SystemGrant is the named escape hatch, and it is
exported — a handler can construct a Grant nobody authorized. What catches
that is aru doctor, a lint, not the type system, with the rules
system-grant-outside-scope and system-grant-without-tenant.
Zero direct third-party dependencies. golang.org/x/crypto arrives indirectly,
through hesape, which is the only place it is used; CI refuses a second one.
11,901 lines of production code and 12,466 of test, across 59 test files —
go test -race ./... passes.
Today, most of what this module exports — security, data, http, jobs,
events, mail, observability, scheduler, storage, validation, view,
arandutest — is a compatibility alias: the implementation moved to the sibling
hesape repository, and each package's own doc comment names the import path
that replaces it. kernel and config are bridges too, pointing one directory
across at foundation and foundation/bootstrap. All of them go in v1.0.0.
What stays here for good is the boot sequence: foundation composes the
application, and foundation/bootstrap reads its typed configuration.
Install
go get github.com/arandu-io/framework
Learning Arandu
The API reference is generated from the doc comments and lives on pkg.go.dev. Every exported symbol carries one, and that is deliberate: it is the documentation that cannot drift from the code, because it sits in the same file.
The CLI documents itself. aru help lists every command, and each one explains
what it writes and what to do with it. aru doctor explains what it found and
what breaks, not which rule was violated.
The guide is published at arandu.io/docs, and the site is itself an Arandu application. Where the guide and a doc comment disagree, the doc comment sits next to the code and is the one to trust.
The rest of Arandu
aru is the command line; arandu is the project skeleton it clones; hesape
is the 47-package collection this module is built from; examples is a
complete application to read. The database, cache, queue and file adapters used
to be four repositories of their own; they are hesape packages now, each heavy
driver in a submodule with its own go.mod, because Go has no optional
dependency and a project should pay in go.sum only for what it imports.
Contributing
See CONTRIBUTING.md. Before opening a pull request, the three
commands at the top of that file have to pass. CI runs them and four more that
a laptop has no reason to: a guard on the layout of the test tree, the
dependency budget, an API diff against the last release that fails an
incompatible change carrying no UPGRADE.md entry, and govulncheck.
Security Vulnerabilities
Please review our security policy on how to report a vulnerability. Never open a public issue for one.
License
Open-sourced software licensed under the MIT license.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package arandutest holds the helpers a test needs and an application must not use.
|
Package arandutest holds the helpers a test needs and an application must not use. |
|
Package config holds the typed application configuration.
|
Package config holds the typed application configuration. |
|
Package data defines the data access contract.
|
Package data defines the data access contract. |
|
Package events is domain events with an outbox.
|
Package events is domain events with an outbox. |
|
Package foundation boots the application.
|
Package foundation boots the application. |
|
bootstrap
Package bootstrap is the boot sequence: what runs once, in order, before the application answers anything.
|
Package bootstrap is the boot sequence: what runs once, in order, before the application answers anything. |
|
Package geo bridges the native GEO component into the current Framework router envelope.
|
Package geo bridges the native GEO component into the current Framework router envelope. |
|
Package http is the request and routing layer.
|
Package http is the request and routing layer. |
|
middleware
Package middleware holds the mandatory request pipeline.
|
Package middleware holds the mandatory request pipeline. |
|
internal
|
|
|
routes
Package routes identifies modules that own framework-managed HTTP routes.
|
Package routes identifies modules that own framework-managed HTTP routes. |
|
Package jobs is the queue contract: work that happens after the response.
|
Package jobs is the queue contract: work that happens after the response. |
|
Package kernel boots the application.
|
Package kernel boots the application. |
|
Package mail sends what an application has to say to somebody.
|
Package mail sends what an application has to say to somebody. |
|
modules
|
|
|
auth
Package auth is the first first-party module and the canonical reference: every module the CLI generates has exactly this shape.
|
Package auth is the first first-party module and the canonical reference: every module the CLI generates has exactly this shape. |
|
Package observability is the reason this framework exists.
|
Package observability is the reason this framework exists. |
|
errorpage
Package errorpage renders the development error page.
|
Package errorpage renders the development error page. |
|
Package scheduler runs the tasks modules declare.
|
Package scheduler runs the tasks modules declare. |
|
Package security holds the authorization primitives of the framework.
|
Package security holds the authorization primitives of the framework. |
|
Package storage is the file contract: what a tenant uploaded, and where it went.
|
Package storage is the file contract: what a tenant uploaded, and where it went. |
|
Package test holds the helpers a test needs and an application must not use.
|
Package test holds the helpers a test needs and an application must not use. |
|
browser
Package browser drives an application in a real browser, the way the person using it does, and fails the test on what that person would have seen go wrong.
|
Package browser drives an application in a real browser, the way the person using it does, and fails the test on what that person would have seen go wrong. |
|
browser/cdp
Package cdp is the default browser driver: Chrome or Chromium, driven over the Chrome DevTools Protocol through the debugging pipe the browser opens on its file descriptors 3 and 4 (--remote-debugging-pipe).
|
Package cdp is the default browser driver: Chrome or Chromium, driven over the Chrome DevTools Protocol through the debugging pipe the browser opens on its file descriptors 3 and 4 (--remote-debugging-pipe). |
|
browser/conformance
Package conformance is the suite every browser driver passes.
|
Package conformance is the suite every browser driver passes. |
|
conformance
Package conformance is the set of authentication suites an Arandu application runs against itself, each in one call from its tests/Conformance.
|
Package conformance is the set of authentication suites an Arandu application runs against itself, each in one call from its tests/Conformance. |
|
internal/dbclone
Package dbclone makes one Postgres database per test out of a template migrated once.
|
Package dbclone makes one Postgres database per test out of a template migrated once. |
|
openapi
Package openapi checks what an application answers against the OpenAPI document it publishes.
|
Package openapi checks what an application answers against the OpenAPI document it publishes. |
|
servertrace
Package servertrace records what the server did for each request a test sent -- the lines it logged, the statements it ran and the Policy decisions it was answered -- under the request id the response carries.
|
Package servertrace records what the server did for each request a test sent -- the lines it logged, the statements it ran and the Policy decisions it was answered -- under the request id the response carries. |
|
trace
Package trace is the one format a browser test leaves behind when it fails: the steps it took, a PNG and the DOM after each one, the network, the console, the failures, and a section the server fills with what it did for each request.
|
Package trace is the one format a browser test leaves behind when it fails: the steps it took, a PNG and the DOM after each one, the network, the console, the failures, and a section the server fills with what it did for each request. |
|
Package tests is the base the suites of this module build on.
|
Package tests is the base the suites of this module build on. |
|
Package validation checks a submitted form against a set of rules.
|
Package validation checks a submitted form against a set of rules. |
|
Package view is the view layer: kyse for markup, HTMX for interaction, ui.js for client behaviour, Tailwind for style.
|
Package view is the view layer: kyse for markup, HTMX for interaction, ui.js for client behaviour, Tailwind for style. |
|
Package webhook registers the native webhook component on the Framework router envelope.
|
Package webhook registers the native webhook component on the Framework router envelope. |