Ambiorix: Ambiorix

In JohnCoene/ambiorix: Web Framework Inspired by 'Express.js'

Ambiorix

Description

Web server.

Value

An object of class Ambiorix from which one can add routes, routers, and run the application.

Super class

ambiorix::Routing -> Ambiorix

Public fields

not_found

404 Response, must be a handler function that accepts the request and the response, by default uses response_404().

error

500 response when the route errors, must a handler function that accepts the request and the response, by default uses response_500().

on_stop

Callback function to run when the app stops, takes no argument.

Active bindings

port

Port to run the application.

host

Host to run the application.

limit

Max body size, defaults to 5 * 1024 * 1024.

Methods

Public methods

• Ambiorix$new()

• Ambiorix$cache_templates()

• Ambiorix$listen()

• Ambiorix$set_404()

• Ambiorix$set_error()

• Ambiorix$static()

• Ambiorix$start()

• Ambiorix$serialiser()

• Ambiorix$stop()

• Ambiorix$print()

• Ambiorix$clone()

Inherited methods

• ambiorix::Routing$all()
• ambiorix::Routing$delete()
• ambiorix::Routing$engine()
• ambiorix::Routing$get()
• ambiorix::Routing$get_middleware()
• ambiorix::Routing$get_receivers()
• ambiorix::Routing$get_routes()
• ambiorix::Routing$options()
• ambiorix::Routing$patch()
• ambiorix::Routing$post()
• ambiorix::Routing$prepare()
• ambiorix::Routing$put()
• ambiorix::Routing$receive()
• ambiorix::Routing$use()

---

Method new()

Usage

Ambiorix$new(
  host = getOption("ambiorix.host", "0.0.0.0"),
  port = getOption("ambiorix.port", NULL),
  log = getOption("ambiorix.logger", TRUE)
)

Arguments

host

A string defining the host.

port

Integer defining the port, defaults to ambiorix.port option: uses a random port if NULL.

log

Whether to generate a log of events.

Details

Define the webserver.

---

Method cache_templates()

Usage

Ambiorix$cache_templates()

Details

Cache templates in memory instead of reading them from disk.

---

Method listen()

Usage

Ambiorix$listen(port)

Arguments

port

Port number.

Details

Specifies the port to listen on.

Examples

app <- Ambiorix$new()

app$listen(3000L)

app$get("/", function(req, res){
 res$send("Using {ambiorix}!")
})

if(interactive())
 app$start()

---

Method set_404()

Usage

Ambiorix$set_404(handler)

Arguments

handler

Function that accepts the request and returns an object describing an httpuv response, e.g.: response().

Details

Sets the 404 page.

Examples

app <- Ambiorix$new()

app$set_404(function(req, res){
 res$send("Nothing found here")
})

app$get("/", function(req, res){
 res$send("Using {ambiorix}!")
})

if(interactive())
 app$start()

---

Method set_error()

Usage

Ambiorix$set_error(handler)

Arguments

handler

Function that accepts a request, response and an error object.

Details

Sets the error handler.

Examples

# my custom error handler:
error_handler <- \(req, res, error) {
  if (!is.null(error)) {
    error_msg <- conditionMessage(error)
    cli::cli_alert_danger("Error: {error_msg}")
  }
  response <- list(
    code = 500L,
    msg = "Uhhmmm... Looks like there's an error from our side :("
  )
  res$
    set_status(500L)$
    json(response)
}

# handler for GET at /whoami:
whoami <- \(req, res) {
  # simulate error (object 'Pikachu' is not defined)
  print(Pikachu)
}

app <- Ambiorix$
  new()$
  set_error(error_handler)$
  get("/whoami", whoami)

if (interactive()) {
  app$start(open = FALSE)
}

---

Method static()

Usage

Ambiorix$static(path, uri = "www")

Arguments

path

Local path to directory of assets.

uri

URL path where the directory will be available.

Details

Static directories

---

Method start()

Usage

Ambiorix$start(port = NULL, host = NULL, open = interactive())

Arguments

port

Integer defining the port, defaults to ambiorix.port option: uses a random port if NULL.

host

A string defining the host.

open

Whether to open the app the browser.

Details

Start Start the webserver.

Examples

app <- Ambiorix$new()

app$get("/", function(req, res){
 res$send("Using {ambiorix}!")
})

if(interactive())
 app$start(port = 3000L)

---

Method serialiser()

Usage

Ambiorix$serialiser(handler)

Arguments

handler

Function to use to serialise. This function should accept two arguments: the object to serialise and ....

Details

Define Serialiser

Examples

app <- Ambiorix$new()

app$serialiser(function(data, ...){
 jsonlite::toJSON(x, ..., pretty = TRUE)
})

app$get("/", function(req, res){
 res$send("Using {ambiorix}!")
})

if(interactive())
 app$start()

---

Method stop()

Usage

Ambiorix$stop()

Details

Stop Stop the webserver.

---

Method print()

Usage

Ambiorix$print()

Details

Print

---

Method clone()

The objects of this class are cloneable with this method.

Usage

Ambiorix$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

app <- Ambiorix$new()

app$get("/", function(req, res){
 res$send("Using {ambiorix}!")
})

app$on_stop <- function(){
 cat("Bye!\n")
}

if(interactive())
 app$start()


## ------------------------------------------------
## Method `Ambiorix$listen`
## ------------------------------------------------

app <- Ambiorix$new()

app$listen(3000L)

app$get("/", function(req, res){
 res$send("Using {ambiorix}!")
})

if(interactive())
 app$start()

## ------------------------------------------------
## Method `Ambiorix$set_404`
## ------------------------------------------------

app <- Ambiorix$new()

app$set_404(function(req, res){
 res$send("Nothing found here")
})

app$get("/", function(req, res){
 res$send("Using {ambiorix}!")
})

if(interactive())
 app$start()

## ------------------------------------------------
## Method `Ambiorix$set_error`
## ------------------------------------------------

# my custom error handler:
error_handler <- \(req, res, error) {
  if (!is.null(error)) {
    error_msg <- conditionMessage(error)
    cli::cli_alert_danger("Error: {error_msg}")
  }
  response <- list(
    code = 500L,
    msg = "Uhhmmm... Looks like there's an error from our side :("
  )
  res$
    set_status(500L)$
    json(response)
}

# handler for GET at /whoami:
whoami <- \(req, res) {
  # simulate error (object 'Pikachu' is not defined)
  print(Pikachu)
}

app <- Ambiorix$
  new()$
  set_error(error_handler)$
  get("/whoami", whoami)

if (interactive()) {
  app$start(open = FALSE)
}

## ------------------------------------------------
## Method `Ambiorix$start`
## ------------------------------------------------

app <- Ambiorix$new()

app$get("/", function(req, res){
 res$send("Using {ambiorix}!")
})

if(interactive())
 app$start(port = 3000L)

## ------------------------------------------------
## Method `Ambiorix$serialiser`
## ------------------------------------------------

app <- Ambiorix$new()

app$serialiser(function(data, ...){
 jsonlite::toJSON(x, ..., pretty = TRUE)
})

app$get("/", function(req, res){
 res$send("Using {ambiorix}!")
})

if(interactive())
 app$start()

JohnCoene/ambiorix documentation built on Jan. 17, 2025, 11:11 p.m.