Miscellaneous

All functions are located in the com.biffweb namespace.

(use-hawk
 {:biff.hawk/keys [on-save exts paths],
  :or {paths ["src" "resources"]},
  :as ctx})

Deprecated. Use use-beholder instead.

use-beholder is a drop-in replacement for use-hawk, except that keys must be
prefixed with :biff.beholder/ instead of :biff.hawk/

(use-beholder
 {:biff.beholder/keys [on-save exts paths enabled],
  :or {paths ["src" "resources"], enabled true},
  :as ctx})

A Biff component that runs code when files are changed, via Beholder.

See https://github.com/nextjournal/beholder.

enabled:  If false, this component is a no-op. Default true.
on-save:  A single-argument function to call whenever a file is saved.
          Receives the system map as a parameter. Subsequent file saves
          that occur within one second are ignored.
paths:    A collection of root directories to monitor for file changes.
exts:     If exts is non-empty, files that don't end in one of the extensions
          will be ignored.

(reitit-handler {:keys [router routes on-error], :as opts})

Convenience wrapper for reitit.ring/ring-handler.

Only one of router or routes needs to be given. If you pass in routes, it
will be wrapped with (reitit.ring/router routes). on-error is an optional
Ring handler. The request map passed to it will include a :status key (either
404, 405, or 406). on-error can also be supplied by setting
:biff.middleware/on-error on the system map.

Includes reitit.ring/redirect-trailing-slash-handler.

(use-jetty
 {:biff/keys [host port handler],
  :or {host "localhost", port 8080},
  :as ctx})

A Biff component that starts a Jetty web server.

(jwt-encrypt {:keys [exp-in], :as claims} secret)

Convenience wrapper for buddy.sign.jwt/encrypt.

Returns a string token. secret is a base64-encoded string used to encrypt the
token. A secret can be generated with (com.biffweb/generate-secret 32).
exp-in is the number of seconds in the future at which the token should
expire. claims is passed to buddy.sign.jwt/encrypt as-is, except that :exp is
set based on exp-in.

(jwt-decrypt token secret)

Convenience wrapper for buddy.sign.jwt/decrypt.

token is a string as returned by jwt-encrypt. secret is a base64-encoded
string that was used to encrypt token. Returns the claims passed to
jwt-encrypt. Returns nil if the token is invalid or expired.

(use-chime
 {:keys [biff/modules biff/plugins biff/features biff.chime/tasks],
  :as ctx})

A Biff component for running scheduled tasks with Chime (https://github.com/jarohen/chime)

modules:  A var containing a collection of module maps. Each module map may
          contain a :tasks key, which contains a collection of task maps.
plugins:  Deprecated. Alias for modules. modules takes precedence.
features: Deprecated. Alias for plugins. modules and plugins take precedence.
tasks:    Deprecated. Use modules instead. If set, takes precedence over
          modules.

For example:
(def module
  {:tasks [{:task (fn [ctx] (println "hello there"))
            :schedule (iterate #(biff/add-seconds % 60) (java.util.Date.))}]})

(mailersend
 {:keys [mailersend/api-key mailersend/defaults], :as ctx}
 opts)

Sends an email with MailerSend.

See https://developers.mailersend.com/api/v1/email.html#send-an-email. Does a
POST request on the /v1/email endpoint and returns the X-Message-Id response
header on success. On failure, prints an error message and returns false.

opts is a map which will be converted to JSON and included as the body of the
request. defaults is a map from paths to default values. It will be combined
with opts. For example:

(mailersend {:mailersend/api-key "..."
             :mailersend/defaults {[:from :email] "hello@mail.example.com"
                                   [:from :name] "My Application"
                                   [:reply_to :email] "hello@example.com"
                                   [:reply_to :name] "My Application"}}
            {:to [{:email "recipient@example.com"}]
             :subject "Some subject"
             :text "Some text"
             :from {:name "This will override the default value of 'My Application'"}})

(generate-secret length)

Generates a random byte array with (SecureRandom/getInstanceStrong) and returns it as a base64 string.

This function will block if there isn't enough entropy available.

(use-random-default-secrets ctx)

Deprecated. If secrets aren't set in secrets.env, they can be generated with
`bb generate-secrets`.

A Biff component that merges temporary secrets into the system map if needed.

Sets :biff.middleware/cookie-secret and :biff/jwt-secret if they are nil. The
secrets will not persist if the system is restarted. Can be useful in
development. e.g. a config.edn.TEMPLATE can be checked into a project's
repository without secrets set. Contributers can run the project by copying
the file to config.edn, without needing to modify it.

This component should not be relied upon in production; instead you should
save secrets in config.edn. This is done automatically at project setup time
for new Biff projects.

(use-secrets ctx)

Sets :biff/secret to a function which will return the value for a given secret.
Also ensures that secrets for :biff.middleware/cookie-secret and
:biff/jwt-secret are set. If they aren't, exits with an error message.

For example, if the environment variable SOME_API_KEY is set to FOO and
the :some-service/api-key config option is set to "SOME_API_KEY", then
you can get the API key like so:

(defn handler [{:keys [biff/secret]}]]
  (let [api-key (secret :some-service/api-key)]
    ...))

You could also just call (System/getenv "SOME_API_KEY"), which is fine in
application code. But Biff's internal code uses :biff/secret so that you can
override it if you want to store secrets somewhere else.

(merge-context
 {:keys [biff/merge-context-fn],
  :or {merge-context-fn assoc-db},
  :as ctx})

Returns the context map with additional data merged in.

Calls (merge-context-fn ctx). By default, adds an XT database object to
:biff/db.

(doc-schema
 {:keys [required optional closed wildcards],
  :or {closed true},
  :as opts})

Returns a [:map ...] schema for use with Malli.

Example:

(doc-schema
 {:required [:user/name
             [:user/email :string]]
  :optional [[:user/phone :string]]})
=>
[:map
 {:closed true}
 :user/name
 [:user/email :string]
 [:user/phone {:optional true} :string]]

wildcards is map from namespace symbols to predicate functions. Any key-value
pairs in the map with a matching key namespace will be valid iff the value
passes the predicate function. For example:

(doc-schema
 {:required [[:user/email :string]]
  :wildcards {'user.signup-params string?}})

;; Valid:
{:user/email "hello@example.com"
 :user.signup-params/utm_source "twitter"}

(use-htmx-refresh {:keys [biff/handler biff.refresh/enabled], :as ctx})

Refreshes the browser automatically when you save a file.

 If `enabled` is true, wraps `handler` with middleware that will insert some
 htmx websocket code into HTML responses. Adds a callback function to
 (:biff.eval/on-eval ctx) that will send a refresh command via websocket (see
 biff/eval-files!). If you have a compilation error, that will be displayed
 instead of refreshing.