Applications and resources

Public

hoplite.core/app tags a map as an application. The map is immutable application data, not an imperative server builder.

(h/app {:name "catalog"
        :resources [...]})

Passing a callable instead of a map creates a catch-all application with one ANY /*path route:

(h/app #'handler)

Resource trees

Resources are nested vectors. Paths must be empty or begin with /; child paths are joined to their parent.

["/users"
 {:get {:handler #'list-users}}
 ["/:id"
  {:get {:handler #'get-user}
   :delete {:handler #'delete-user}}]]

At build time, Hoplite flattens the tree into method/path/handler records. An application with no operations is rejected.

Operation fields

Field	Required	Purpose
:handler	Yes	Callable or Var resolved for the route
:name	No	Stable operation name
:summary	No	Human-readable description used by OpenAPI output
:route/adapter	No	:raw, :request (default), or :request+hta; overrides the application default

Fixed upstreams

An application may declare build-time proxy prefixes for a known service origin:

(h/app
  {:name "beacon"
   :proxies
   [{:path "/space/"
     :upstream "https://greenways.space/beacon/v1/"}]
   :resources
   [["/health" {:get {:handler #'health}}]]})

Hoplite renders each entry as a more-specific Nginx prefix location before the Hara application location. The incoming method, query and body pass through Nginx without entering a Hara worker.

Both values are immutable application configuration. The local path and upstream path must begin and end with /; variables, credentials, query strings, fragments and dot segments are rejected. Remote origins require HTTPS. Plain HTTP is accepted only for explicit loopback development origins.

A fixed upstream is a transport route, not an authentication grant. Hoplite strips ambient cookies, browser Origin and forwarding headers before sending the request. Applications should use an explicit signed or bearer protocol in headers when the upstream requires identity. See Static upstreams for the complete boundary.

Validation

Hoplite rejects relative resource paths, operations without handlers, empty applications, duplicate application IDs, ambiguous default applications sharing a port, duplicate proxy prefixes, dynamic upstreams, and insecure non-loopback HTTP origins.