Bodge.app

Docs

Contents: Examples | How it Works | The Lua Environment | Bodge Lua APIs

Examples

To get an idea of what you could do with bodge, check out some examples.

How it Works

1. Add a domain.

You may choose any single-level subdomain under bodge.link that is not already in use.

Add Domain
Screenshot of Adding a Domain

2. Add a script.

This means choosing a URL path under your domain which will trigger your script to run.

Add Script
Screenshot of Adding a Script

3. Write your script.

Write a Lua script. It can do whatever you want.

Write Script
Screenshot of Writing a Script

4. Deploy the script.

One-click on the 'deploy' button and your script is live.

$ curl https://example.bodge.link/any/path/you/want
Hello, world!

The Lua Environment

Bodge runs your script in a custom sandboxed Lua 5.4 based environment. The Lua standard environment is available, except OS-level facilities like command execution and filesystem access.

See the Lua Reference Manual for details.

Script Structure

Scripts are run as if they are the body of a function which receives a request parameter and returns a response.

request parameter

request is a table representing the incoming HTTP request that triggered this exection with the following fields:

method
The HTTP method of the request as a string.
path
The path portion of the URL as an unparsed string.
querystring
The query portion of the URL as an unparsed string.
query
A table of key-value pairs parsed from the query portion of the URL.
headers
A table of key-value pairs parsed from the headers of the HTTP request.
body
The raw content of the body as a string. (Note: In Lua strings can contain arbitrary binary data.)
form
A table of key-value pairs parsed from a request body with the content type multipart/form-data or application/x-www-form-urlencoded. nil for other content types.
files
A table of uploaded files, by filename, parsed from a request body with the content type multipart/form-data. nil for other content types.

return values

Scripts are evaluated and whatever is returned by your script is used to build the HTTP response.

You script can return one or more values, the return values are interpreted as:

  1. If any string value is returned, the first string value is sent as the body and the first table value (if any) is a list of headers to be applied to the response.
  2. If no string value is returned, but a table is returned, the first table is JSON-encoded and sent as the body, the second table (if any) is a list of headers to be applied to the response.
  3. If a number with an integer representation which corresponds to a valid HTTP status code is returned, it is used to set the response's status. Otherwise, a status of "200 OK" is used.
  4. All other values are currently ignored.
Examples
return "Hello, world!"

return { this = "becomes JSON" }

return 404, "Couldn't Find The Thing"

return "<h1>Helo, World!</h1>", {["Content-Type"] = "text/html"}

Bodge Lua APIs

Bodge provides some easy to use APIs for common use cases. Each of these modules are loaded into your script's global environment, ready to be called.

alert
Alerts
base64
Base64 Encoding and Decoding
base64.url
Base64url Encoding and Decoding
crypto
Common Cryptographic Functions
email
Email Sending
http
Outbound HTTP Requests
json
Json Encoding and Decoding
lock
Domain-Wide Mutexes for Synchronization
storage
Simple Key/Value Storage

Third-Party Modules

A select number of third-party modules are available. These modules are not loaded by default, they can be loaded with a standard call to require.

dkjson - JSON Encoding and Decoding

Ref: https://dkolf.de/dkjson-lua/documentation

License: MIT

Copyright (C) 2010-2021 David Heiko Kolf

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

htmlparser - HTML Parser

Ref: https://msva.github.io/lua-htmlparser/

License: LGPL 3.0 GNU Lesser General Public License (LGPL)
xml2lua - XML Parser

Ref: https://github.com/manoelcampos/xml2lua?tab=readme-ov-file#2-how-to-use

License: MIT

Copyright (c) 2016 Manoel Campos da Silva Filho

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

lustache - mustache templates

Ref: https://github.com/Olivine-Labs/lustache?tab=readme-ov-file#templates

License: MIT

Copyright (c) 2012 Olivine Labs

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.