Router Functions in Routzie

Introduction

The Routzie router allows you to expose endpoints directly from your machine. These endpoints are simply marked functions that can be called externally via HTTP. You can handle multiple HTTP methods (GET, POST, etc.) and use route parameters for dynamic routing.

Defining Routes

Use the route function to define an endpoint. You specify allowed HTTP methods, the path, and an async handler function. The handler receives a ProcessedRequest object containing request data, parameters, headers, and body.

Example: JSON Route

route(['GET'], 'endpoint', async function(req: ProcessedRequest) {
  const data = {
    count: 123,
    property: 'Hello world',
  }
  return new RouteResult(data, 200, {
    ['Content-Type']: 'application/json',
  })
})

This route responds with a JSON object and sets the correct content type.

Basic Authorization

You can easily protect endpoints using HTTP Basic Auth. Use the basicAuthorization helper:

route(['GET'], 'endpoint', async function(req: ProcessedRequest) {
  return basicAuthorization(
    req,
    'Please authorize',
    [{ username: 'test', password: 'test' }],
    async (req: ProcessedRequest, username: string) => {
      const data = {
        count: 123,
        property: 'Hello world',
      }
      return new RouteResult(data, 200, {
        ['Content-Type']: 'application/json',
      })
    },
  )
})

If the credentials match, the callback is called with the authorized username.

Handling Form Data and Files

You can receive form data, including file uploads, using FormData and BlobReference:

route(['POST'], 'endpoint', async function(req: ProcessedRequest) {
  if (req.body instanceof FormData) {
    const blob: BlobReference = req.body.getValue('image') as BlobReference
    if (!(blob instanceof BlobReference)) {
      return new RouteResult('Bad request', 400)
    }
    // Send blob back
    return new RouteResult(blob, 200)
  }
  return new RouteResult('Bad request', 400)
})

This route expects a multipart form with an image field and returns the uploaded image.

Receiving and Sending Blobs

You can receive and send binary data (blobs) directly:

route(['POST'], 'endpoint', async function(req: ProcessedRequest) {
  if (req.body instanceof BlobReference) {
    // Send it back
    return new RouteResult(req.body, 200)
  }
  return new RouteResult('Bad request', 400)
})

Sending Form Data from Endpoint

You can also send form data from your endpoint:

route(['GET'], 'endpoint', async function(req: ProcessedRequest) {
  const formData = new FormData()
  formData.append('name', 'Hello world')
  // Send it
  return new RouteResult(formData, 200)
})

Route Parameters

Define dynamic routes with parameters using :parameter syntax. Access them via req.params:

route(['GET'], 'endpoint/:parameter', async function(req: ProcessedRequest) {
  const data = {
    received: req.params.parameter,
  }
  return new RouteResult(data, 200)
})

This route will match e.g. /endpoint/123 and return { received: "123" }.

Handling CORS

To enable CORS (Cross-Origin Resource Sharing) for your endpoints, use the setCorsOptions helper at the beginning of your route handler:

setCorsOptions({
  origin: '*',
  allowedHeaders: 'Content-Type, Accept, Origin'
})

This will automatically set the necessary CORS headers for the response.

Note: Calling setCorsOptions will affect all subsequently defined routes. If you call setCorsOptions again before defining more routes, those routes will use the new options. Each call sets the CORS options for all routes defined after it.

If you need more advanced CORS logic, you can manually set headers in your route handler using:

return new RouteResult(data, 200, {
  ['Access-Control-Allow-Origin']: '*',
  ['Access-Control-Allow-Headers']: 'Content-Type, Accept, Origin',
  // ...other headers
})

If you do not use setCorsOptions, you are responsible for setting CORS headers yourself.

Summary

• Use route to expose endpoints with any HTTP method and path.
• Return any data type: JSON, form data, blobs, etc.
• Use basicAuthorization for simple HTTP authentication.
• Handle form data and file uploads with FormData and BlobReference.
• Use route parameters for dynamic endpoints.

For more advanced scenarios, combine these features to build flexible APIs and web interfaces directly in your machine code.