Skip to content

Latest commit

 

History

History
1685 lines (1128 loc) · 69.4 KB

API.md

File metadata and controls

1685 lines (1128 loc) · 69.4 KB
Raw

Table of contents

triangulum.build-db

-main

(-main & args)

A set of tools for building and maintaining the project database with Postgres.

Source

triangulum.cli

Provides a command-line interface (CLI) for Triangulum applications. It includes functions for parsing command-line options, displaying usage information, and checking for errors in the provided arguments.

get-cli-options

(get-cli-options args cli-options cli-actions alias-str & [config])

Checks for a valid call from the CLI and returns the users options.

Takes the command-line arguments, a map of CLI options, a map of CLI actions, an alias string, and an optional config map.

Example:

(def cli-options {...})

(def cli-actions {...})
(def alias-str "...")

(get-cli-options command-line-args cli-options cli-actions alias-str)

Source

triangulum.config

-main

(-main & args)

Configuration management.

Source

get-config

(get-config & all-keys)

Retrieves the key k from the config file. Can also be called with the keys leading to a config. Examples:

(get-config :mail) -> {:host "google.com" :port 543}
(get-config :mail :host) -> "google.com"
(get-config :triangulum.email/host) -> "google.com"
(get-config :triangulum.views/title :en) -> "english"

Source

load-config

(load-config)
(load-config new-config-file)

Re/loads a configuration file. Defaults to the last loaded file, or config.edn.

Source

namespaced-config?

(namespaced-config? config)

Returns true if the given configuration map is namespaced, otherwise false.

Source

nested-config?

(nested-config? config)

Returns true if the given configuration map is unnamespaced nested, otherwise false.

Source

split-ns-key

(split-ns-key ns-key)

Given a namespaced key, returns a vector of unnamespaced keys.

Source

valid-config?

(valid-config? {:keys [file]})

Validates file as a configuration file.

Source

triangulum.database

To use triangulum.database, first add your database connection configurations to a config.edn file in your project's root directory.

For example:

;; config.edn
{:database {:host     "localhost"
          :port     5432
          :dbname   "pyregence"
          :user     "pyregence"
          :password "pyregence"}}

To run a postgres sql command use [call-sql](#triangulum.database/call-sql). Currently [call-sql](#triangulum.database/call-sql) only works with postgres. With the second parameter can be an optional settings map (default values shown below).

(call-sql "function" {:log? true :use-vec? false} "param1" "param2" ... "paramN")

To run a sqllite3 sql command use call-sqlite. An existing sqllite3 database must be provided.

(call-sqlite "select * from table" "path/db-file")

To insert new rows or update existing rows use insert-rows! and update-rows!. If fields are not provided, the first row will be assumed to be the field names.

(insert-rows! table-name rows-vector fields-map)
(update-rows! table-name rows-vector column-to-update fields-map)

call-sql

(call-sql sql-fn-name & opts+args)

Currently call-sql only works with postgres. The second parameter can be an optional settings map.

Defaults values are: {:log? true :use-vec? false}

Source

call-sqlite

(call-sqlite query file-path)

Runs a sqllite3 sql command. An existing sqllite3 database must be provided.

Source

insert-rows!

(insert-rows! table rows)
(insert-rows! table rows fields)

Insert new rows from 3d vector. If the optional fields are not provided, the first row will be assumed to be the field names.

Source

p-insert-rows!

(p-insert-rows! table rows)
(p-insert-rows! table rows fields)

A parallel implementation of insert-rows!

Source

p-update-rows!

(p-update-rows! table rows id-key)
(p-update-rows! table rows id-key fields)

A parallel implementation of update-rows!

Source

sql-primitive

Return single value for queries that return a value instead of a table.

Source

update-rows!

(update-rows! table rows id-key)
(update-rows! table rows id-key fields)

Updates existing rows from a 3d vector. One of the columns must be a identifier for the update command. If the optional fields are not provided, the first row will be assumed to be the field names.

Source

triangulum.email

Provides some functionality for sending email from an SMTP server. Given the configuration inside :mail:

  • :host - Hostname of the SMTP server.
  • :user - Email account to use via SMTP (and which emails will be addressed from)
  • :pass - Password to use via SMTP.
  • :port - Port to use for SMTP.
  • :base-url - The host's host url, used when sending links in emails.

email?

(email? string)

Checks if string is email.

Source

get-base-url

(get-base-url)

Gets the homepage url.

Source

send-mail

(send-mail to-addresses cc-addresses bcc-addresses subject body content-type)

Sends an email with a given subject and body to specified recipients.

This function uses the [send-postal](#triangulum.email/send-postal) internal function to send the email. It logs the success or failure of sending this email.

Arguments: to-addresses - a collection of email addresses to which the email will be sent cc-addresses - a collection of email addresses to which the email will be carbon copied bcc-addresses - a collection of email addresses to which the email will be blind carbon copied subject - a string representing the subject of the email body - a string representing the body of the email content-type - a keyword indicating the content type of the email, either :text for 'text/plain' or :html for 'text/html'

Returns: Result map returned by [send-postal](#triangulum.email/send-postal).

Source

triangulum.errors

Error handling utilities for the Triangulum application. It includes functions and macros to handle exceptions and log errors.

init-throw

(init-throw message)
(init-throw message data)
(init-throw message data cause)

Takes a message string as input and throws an exception with the provided message.

Example: (init-throw "Error: Invalid input"))

Source

nil-on-error

(nil-on-error & body)

Function.

Catches exception and returns nil if its body throws an exception.

Example:

(nil-on-error (/ 1 0)) ; Returns nil
(nil-on-error (+ 2 3)) ; Returns 5

Source

try-catch-throw

(try-catch-throw try-fn message)

Takes a function try-fn and a message string as input. Executes try-fn and, if it throws an exception, catches the exception, logs the error, and then throws an exception with the augmented input message.

Example:

(try-catch-throw (fn [] (throw (ex-info "Initial error" {}))) "Augmented error message")

Source

triangulum.git

current-version

(current-version)

Return current latest tag version from the configured tags url of repo.

Source

get-tags-url

(get-tags-url)

Gets repo tags url from config.edn.

Source

triangulum.handler

authenticated-routing-handler

(authenticated-routing-handler {:keys [uri request-method], :as request})

Routing Handler that delegates authentication & redirection to handlers specified in your config.edn

Source

case-insensitive-substring?

(case-insensitive-substring? s substr)

True if s includes substr regardless of case.

Source

create-handler-stack

(create-handler-stack routing-handler ssl? reload?)

Create the Ring handler stack.

Source

development-app

Handler function for development (figwheel).

Source

get-cookie-store

(get-cookie-store)

Computes a new ring.middleware.session.cookie/cookie-store object.

Source

optional-middleware

(optional-middleware handler mw use?)

Conditionally apply a middleware.

Source

parse-query-string

(parse-query-string query-string)

Parses query strings and returns a params map.

Source

random-string

(random-string n)

Returns a random alphanumeric string of length n.

Source

string-to-bytes

(string-to-bytes s)

Converts a string into a byte array.

Source

wrap-bad-uri

(wrap-bad-uri handler)

Wrapper that checks if the request url contains a bad token from the provided set and returns a forbidden-response if so; otherwise, passes the request to the provided handler.

Source

wrap-edn-params

(wrap-edn-params handler)

Wrapper that parses request query strings and puts in :params request map.

Source

wrap-exceptions

(wrap-exceptions handler)

Wrapper to manage exception handling, logging it and responding with 500 in case of an exception.

Source

wrap-request-logging

(wrap-request-logging handler)

Wrapper that logs the incoming requests.

Source

wrap-response-logging

(wrap-response-logging handler)

Wrapper that logs served responses.

Source

triangulum.https

-main

(-main & args)

A set of tools for using certbot as the server certificate manager.

Source

triangulum.logging

To send a message to the logger use [log](#triangulum.logging/log) or [log-str](#triangulum.logging/log-str). [log](#triangulum.logging/log) can take an optional argument to specify not default behavior. The default values are shown below. [log-str](#triangulum.logging/log-str) always uses the default values.

(log "Hello world" {:newline? true :pprint? false :force-stdout? false})
(log-str "Hello" "world")

By default the above will log to standard out. If you would like to have the system log to YYYY-DD-MM.log, set a log path. You can either specify a path relative to the toplevel directory of the main project repository or an absolute path on your filesystem. The logger will keep the 10 most recent logs (where a new log is created every day at midnight). To stop the logging server set path to "".

log

(log
 data
 &
 {:keys [newline? pprint? force-stdout? truncate?],
  :or {newline? true, pprint? false, force-stdout? false, truncate? true}})

Synchronously create a log entry. Logs will got to standard out as default. A log file location can be specified with set-log-path!.

Default options are {:newline? true :pprint? false :force-stdout? false}

Source

log-str

(log-str & data)

A variadic version of log which concatenates all of the strings into one log line. Uses the default options for log.

Source

set-log-path!

(set-log-path! path)

Sets a path to create file logs. When set to a directory, log files will be created with the date as part of the file name. When an empty string is set logging will be sent to standard out.

Source

triangulum.migrate

*migrations-dir*

Location of migrations dir

Source

migrate!

(migrate! database user user-pass verbose?)

Performs the database migrations stored in the src/sql/changes/ directory. Migrations must be stored in chronological order (e.g. 2021-02-28_add-users-table.sql).

Migrations run inside of a transaction block to ensure the entire migration is completed prior to being committed to the database.

Currently, this tool does not support rollbacks.

If a migration fails, all migrations which follow it will be cancelled.

Migrations which have been completed are stored in a table tri.migrations, and include a SHA-256 hash of the migration file contents. If a migration has been altered, the migrations will fail. This is to ensure consistency as migrations are added.

Source

triangulum.notify

Provides functions to interact with systemd for process management and notifications.

Uses the SDNotify Java library to send notifications and check the availability of the current process.

The functions in this namespace allow you to check if the process is managed by systemd, send "ready," "reloading," and "stopping" messages, and send custom status messages.

These functions can be helpful when integrating your application with systemd for better process supervision and management.

available?

(available?)

Checks if this process is a process managed by systemd.

Source

ready!

(ready!)

Sends ready message to systemd. Systemd file must include Type=notify to be used.

Source

reloading!

(reloading!)

Sends reloading message to systemd. Must call send-notify! once reloading has been completed.

Source

send-status!

(send-status! s)

Sends status message to systemd. (e.g. (send-status! "READY=1")).

Source

stopping!

(stopping!)

Sends stopping message to systemd.

Source

triangulum.packaging

assert-required

(assert-required task params required)

Check that each key in required coll is a key in params and throw if required are missing in params, otherwise return nil.

Source

assert-specs

(assert-specs task params & key-specs)

Check that key in params satisfies the spec. Throw if it exists and does not conform to the spec, otherwise return nil.

Source

basis

Basis map, which contains the root and project deps.edn maps plus some additional required keys.

Source

build-folder

Directory to contain generated JARs and a directory of JAR contents.

Source

build-jar

(build-jar {:keys [lib-name src-dirs resource-dirs], :or {src-dirs ["src"], resource-dirs ["resources"]}, :as params})

Create a JAR suitable for deployment and use as a library.

Source

build-uberjar

(build-uberjar
 {:keys [app-name main-ns src-dirs resource-dirs bindings compile-opts java-opts manifest],
  :or {src-dirs ["src"], resource-dirs ["resources"], bindings {}, compile-opts {}, java-opts [], manifest {}},
  :as params})

Create an UberJAR suitable for deployment and use as an application.

Source

clean

(clean _)

Delete the build folder and its contents.

Source

deploy-jar

(deploy-jar {:keys [lib-name], :as params})

Upload a library JAR to https://clojars.org.

Source

get-calendar-commit-version

(get-calendar-commit-version)

Returns the current git commit's date and hash as YYYY.MM.DD-HASH. Depends on the git command being available on the JVM's $PATH. Must be run from within a git repository.

Source

get-jar-file-name

(get-jar-file-name lib-name version)

Relative path to the generated JAR file.

Source

get-uberjar-file-name

(get-uberjar-file-name app-name version)

Relative path to the generated UberJAR file.

Source

jar-content

Directory to contain the JAR's contents before it is packaged.

Source

print-calendar-commit-version

(print-calendar-commit-version & _)

Utility function for use with clojure -X.

Source

triangulum.response

data-response

(data-response body & [params])

Creates a response object. Body is required. Status, type, and session are optional. When a type keyword is passed, the body is converted to that type, otherwise the body is converted to your config.edn's :server :response-type.

Source

edn-response

(edn-response body & [params])

Creates an edn response type.

Source

forbidden-response

(forbidden-response _)

Returns a forbidden response.

Source

json-response

(json-response body & [params])

Creates a json response type.

Source

no-cross-traffic?

(no-cross-traffic? {:strs [referer host]})

Checks for cross traffic.

Source

transit-response

(transit-response body & [params])

Creates a transit response type.

Source

triangulum.security

hash-digest

(hash-digest input)
(hash-digest input hash-algorithm)

Returns the hex digest of string. Defaults to SHA-256 hash.

Source

hash-file

(hash-file filename)

Returns the SHA-256 digest of a file.

Source

triangulum.server

-main

(-main & args)

Server entry main function.

Source

reload-running-server!

(reload-running-server! {:keys [nrepl-bind nrepl-port]})

Reloads the server namespace and its dependencies.

Source

send-to-nrepl-server!

(send-to-nrepl-server! msg & [{:keys [host port], :or {host "127.0.0.1", port 5555}}])

Sends form to the nrepl server

Source

start-server!

(start-server!
 {:keys
  [http-port
   https-port
   nrepl
   cider-nrepl
   nrepl-bind
   nrepl-port
   mode
   log-dir
   handler
   workers
   keystore-file
   keystore-type
   keystore-password],
  :or
  {nrepl-bind "127.0.0.1",
   nrepl-port 5555,
   keystore-file "./.key/keystore.pkcs12",
   keystore-type "pkcs12",
   keystore-password "foobar",
   log-dir "",
   mode "prod"}})

See README.org -> Web Framework -> triangulum.server for details.

Source

stop-running-server!

(stop-running-server! {:keys [nrepl-bind nrepl-port]})

Sends stop-server! call to the nrepl server.

Source

stop-server!

(stop-server!)

Stops server with workers jobs.

Source

triangulum.sockets

Provides functionality for creating and managing client and server sockets. It includes functions for opening and checking socket connections, sending messages to the server, and starting/stopping socket servers with custom request handlers. This namespace enables communication between distributed systems and allows you to implement networked applications.

send-to-server!

(send-to-server! host port message)

Attempts to send socket message. Returns :success if successful.

Source

socket-open?

(socket-open? host port)

Checks if the socket at host/port is open.

Source

start-socket-server!

(start-socket-server! port handler)

Starts a socket server at port with handler.

Source

stop-socket-server!

(stop-socket-server!)

Stops the socket server at port with handler.

Source

triangulum.systemd

-main

(-main & args)

The entry point for using the tools provided in systemd.clj.

Source

fmt-service-file

(fmt-service-file template {:keys [http https], :as config})

Formats template with the config dictionary.

template must use handlebar syntax (e.g. {{name}}) which matches the keyword in config.

Currently config supports:

  • :repo-dir [string] - Directory to the repository (sets WorkingDirectory)
  • :extra-aliases [string] - Additional aliases to run with startup (e.g. :production)
  • :http [number] - HTTP Port
  • :https [number] - HTTPS Port

Source

triangulum.type-conversion

Provides a collection of functions for converting between different data types and formats, including conversions between numbers, booleans, JSON, and PostgreSQL data types.

clj->json

Convert clj to JSON string.

Source

clj->jsonb

(clj->jsonb clj)

Convert clj to PG jsonb object.

Source

json->clj

(json->clj json)
(json->clj json default)

Convert JSON string to clj equivalent.

Source

json->jsonb

(json->jsonb json)

Convert JSON string to PG jsonb object.

Source

jsonb->clj

(jsonb->clj jsonb)
(jsonb->clj jsonb default)

Convert PG jsonb object to clj equivalent.

Source

jsonb->json

Convert PG jsonb object to json string.

Source

str->pg

(str->pg s pg-type)

Convert string to PG object of pg-type

Source

val->bool

(val->bool v)
(val->bool v default)

Converts a value to a java Boolean. Default value for failed conversion is false.

Source

val->double

(val->double v)
(val->double v default)

Converts a value to a java Double. Default value for failed conversion is -1.0. Note Postgres float is equivalent to java Double.

Source

val->float

(val->float v)
(val->float v default)

Converts a value to a java Float. Default value for failed conversion is -1.0. Note Postgres real is equivalent to java Float.

Source

val->int

(val->int v)
(val->int v default)

Converts a value to a java Integer. Default value for failed conversion is -1.

Source

val->long

(val->long v)
(val->long v default)

Converts a value to a java Long. Default value for failed conversion is -1.

Source

triangulum.utils

Collection of utility functions for various purposes, such as text parsing, shell command execution, response building, and operations on maps and namespaces.

camel->kebab

(camel->kebab camel-string)

Converts camelString to kebab-string.

Source

clj-namespaced-symbol->js-module

(clj-namespaced-symbol->js-module sym)

Given a namespace-qualified symbol, return its string representation as a JS module.

Source

current-year

(current-year)

Returns the current year as an integer.

Source

data-response

(data-response body)
(data-response body {:keys [status type session], :or {status 200, type :edn}, :as params})

DEPRECATED: Use [[triangulum.response/data-response]] instead. Create a response object. Body is required. Status, type, and session are optional. When a type keyword is passed, the body is converted to that type, otherwise the body is converted to edn.

Source

delete-recursively

(delete-recursively dir)

Recursively delete all files and directories under the given directory.

Source

end-with

(end-with s end)

Appends 'end' to the end of the string, if it is not already the end of the string.

Source

filterm

(filterm pred coll)

Takes a map, filters on pred for each MapEntry, returns a map.

Source

find-missing-keys

(find-missing-keys m1 m2)

Returns true if m1's keys are a subset of m2's keys, and that any nested maps also maintain the same property.

Example: (find-missing-keys {:a {:b "c"} :d 0} {:a {:b "e" :g 42} :d 1 :h 2}) ; => true

Source

format-str

(format-str f-str & args)

Use any char after % for format. All % are converted to %s (string).

Source

format-with-dict

(format-with-dict fmt-str m)

Replaces fmt-str with values from m.

NOTE: fmt-str must use handlebars ({{<keyword>}}) wherever a term is to be replaced.

Example:

(format-with-dict "Hi {{name}}! The moon is {{n}} billion years old." {:name "Bob" :n 4.5}) ; => "Hi Bob! The moon is 4.5 billion years old."

Source

kebab->camel

(kebab->camel kebab-string)

Converts kebab-string to camelString.

Source

kebab->snake

(kebab->snake kebab-str)

Converts kebab-str to snake_str.

Source

mapm

(mapm f coll)

Takes a map, applies f to each MapEntry, returns a map.

Source

parse-as-sh-cmd

(parse-as-sh-cmd s)

Split string into an array for use with clojure.java.shell/sh.

Source

path

(path & args)

Takes variadic args and returns a path string. Args can be any type that can be coerced via str.

Example: `(path (io/file "my-dir") "file.csv") ; => "my-dir/file.csv" (on Unix)

Source

remove-end

(remove-end s end)

Removes 'end' from string, only if it exists.

Source

resolve-foreign-symbol

(resolve-foreign-symbol sym)

Given a namespace-qualified symbol, attempt to require its namespace and resolve the symbol within that namespace to a value.

Source

reverse-map

(reverse-map m)

Reverses the key-value pairs in a given map.

Source

sh-exec-with

(sh-exec-with dir env command)

Provides a path (dir) and environment (env) to one bash command and executes it. Returns a map in the following format: {:exit 0 :out 'Output message ' :err ''}

Source

sh-wrapper

(sh-wrapper dir env verbose? & commands)

DEPRECATED: Use [[triangulum.utils/shell-wrapper]] instead. Takes a directory, an environment, a verbosity flag, and bash commands. Executes the commands using the given path and environment, then returns the output (errors by default).

Source

shell-wrapper

(shell-wrapper & args)

A wrapper around babashka.process/shell that logs the output and errors. Accepts an optional opts map as the first argument, followed by the command and its arguments. The :log? key in the opts map can be used to control logging (default is true).

Usage: (shell-wrapper {} "ls" "-l") ; With an opts map (shell-wrapper "ls" "-l") ; Without an opts map (shell-wrapper {:log? false} "ls" "-l") ; Disabling logging

Examples:

  1. Logs the output and errors by default: (shell-wrapper {} "ls" "-l")

  2. Can be called without an opts map, assuming default values: (shell-wrapper "ls" "-l")

  3. Disabling logging using the :log? key in the opts map: (shell-wrapper {:log? false} "ls" "-l")

Source

snake->kebab

(snake->kebab snake_str)

Converts snake_str to kebab-str.

Source

triangulum.views

body->transit

(body->transit body)

Produces a transit response body.

Source

not-found-page

(not-found-page request)

Produces a not found response.

Source

render-page

(render-page uri)

Returns the page's html.

Source

triangulum.worker

Responsible for the management of worker lifecycle within the :server context, specifically those defined under the :workers key. This namespace furnishes functions to initiate and terminate workers, maintaining their current state within an atom.

start-workers!

Starts a set of workers based on the provided configuration. The workers parameter can be either a map (for nested workers) or a vector (for namespaced workers). For nested workers, the map keys are worker names and values are maps with :start (a symbol representing the start function) and :stop keys. The start function is called to start the worker.

For namespaced workers, the vector elements are maps with:

  • ::name - the worker name
  • ::start - a symbol representing the start function
  • ::stop - symbol representing the stop function.

The start function is called to start each worker.

Arguments:

  • workers - a map or vector representing the workers to be started.

Source

stop-workers!

Stops a set of currently running workers. The workers to stop are determined based on the current state of the [workers](#triangulum.worker/workers) atom. If the [workers](#triangulum.worker/workers) atom contains a map, it's assumed to be holding nested workers. If it contains a vector, it's assumed to be holding namespaced workers. The stop function is called with the value to stop each worker.

Source