openstreetmap-serverless-functions

[working-draft] Collection of serverless functions (OpenFaas spec) for use with OpenStreetMap™.

Tip: for sysadmins or people interested in offering hosting, check the openstreetmap-faas-infra.

Functions

api-proxy

• Environment Variables
  • OSM_API_DE_FACTO: https://www.openstreetmap.org/api/0.6
  • CACHE_DRIVER: sqlite
  • CACHE_TTL: 3600

api-rdf

• Environment Variables
  • OSM_API_DE_FACTO: https://www.openstreetmap.org/api/0.6
  • CACHE_DRIVER: sqlite
  • CACHE_TTL: 3600

curl

OpenFaaS test function. Not related to OpenStreetMap. Ignore for now.

okmapabot (draft)

overpass-proxy (draft)

• Environment Variables
  • OVERPASS_API_DE_FACTO: https://overpass-api.de/api/interpreter

See also Overpass Query Language

echo "data=node[name='Gielgen'];out;" > query.osm
curl "https://faas.example.org/overpass-proxy" --data @query.osm --output output.osm

sentimentanalysis

OpenFaaS test function. Not related to OpenStreetMap. Ignore for now.

wiki-as-base

• Environment Variables
  • CACHE_DRIVER: sqlite
  • CACHE_TTL: 3600
  • WIKI_API: https://wiki.openstreetmap.org/w/api.php
  • USER_AGENT: wiki-as-base-faasbot/1.0 (https://github.com/fititnt/openstreetmap-serverless-functions; user@example.org) wiki_as_base-py/{WIKI_AS_BASE_LIB_VERSION}

Currently this FaaS is a syntax sugar for the latest released version of the python package wiki_as_base. See https://github.com/fititnt/wiki_as_base-py for internal details. However, the opinionated defaults:

1. Only accept get requests and by default output the JSON-LD version.
2. If the page title has a suffix .zip, the output will be the wiki_as_base zip package with verbose mode enabled.
3. An GET endpoint __about exposes some metadata, in particular the used version of wiki_as_base.
4. The FaaS endpoint also makes use of local cache with CACHE_TTL. Repeated requests in a short time will overload the de facto backends unless the user makes a serial request of a large amount of different page titles.

wiki-telegram-bot (deprecated)

Deprecated. Replaced by wiki-telegram-faasbot.

wiki-telegram-chatbot (draft)

Almost same variables as the wiki-telegram-faasbot

wiki-telegram-faasbot

• Environment Variables
  • CACHE_DRIVER: sqlite
  • CACHE_TTL: 3600
  • FAAS_BACKEND: https://osm-faas.etica.ai/function/
  • FAAS_ALLOWED: api-rdf,api-proxy,overpass-proxy,wiki-as-base,nodeinfo,cows
  • Telegram Token (only one option necessary)
    • TELEGRAM_BOT_FILE_TOKEN: <secret-name> ^{See on OpenFaaS secrets}
    • TELEGRAM_BOT_TOKEN: <your-token-here>
  • WIKI_API: https://wiki.openstreetmap.org/w/api.php
  • WIKI_WIKIASBASE_MAIN_PAGE: User:EmericusPetro/sandbox/Wiki-as-base
• Requeriments
  • Created bot on Telegram. See From BotFather to 'Hello World'
    • Save the TELEGRAM_BOT_TOKEN. This is equivalent to a password. If compromised, re-generate again with BotFather
  • After installing the wiki-telegram-bot, get the public FaaS endpoint and your function path, and tell Telegram API about it. Example:
    • curl https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setWebhook?url=https://example.org/function/wiki-telegram-bot

Customize /slash commands

curl -X POST -H "Content-Type: application/json" --data '{
  "commands": [
    {"command":"faas","description":"Function as a Service proxy"}
  ]
}' https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setMyCommands
# {"ok":true,"result":true}

Todo's for functions

• Normalize and document strategy on how to change the User Agent to make external requests. Use case: allow de facto backends report or block individual misuse of resources (these FaaS don't store this kind of data)
• Normalize and document (or explicitly say is not enabled) short-lived local cache. Use case: 15 to 60min cache over Wiki requests
• When it makes sense, create an endpoint, like __about to print variables of the FaaS, including versions of used libraries. Use case: debug caching issues and/or use of older versions
• Deal with binary responses. See python3-http-osm on template/README.md
• The chatbots that abstract overpass-proxy should respond with attached file *know limitation on Telegram: 50MB)
• Draft a nominatim-proxy function
• A nominatim-proxy function must be configured to allow faas servers document sufficient information to meet the Nominatim Usage Policy

Guides

Developers of functions

TODO: draft this.

Check out https://docs.openfaas.com/.

Examples of template-stores available:

• This repository
• https://github.com/openfaas/store-functions
• https://github.com/openfaas/python-flask-template
• Any custom Dockerfile ^{But OpenFaaS require some conventions}

Sysadmins

Full example of Infrastructure as Code with Ansible will be released soon... but OpenFaaS core functionality runs mostly with this https://github.com/openfaas/faasd/blob/master/cloud-config.txt.

New! IaC released at https://github.com/fititnt/openstreetmap-faas-infra!

Disclaimers

OpenStreetMap™ is a trademark of the OpenStreetMap Foundation, and is used with their permission. This project is not endorsed by or affiliated with the OpenStreetMap Foundation. (via OSMF Trademark_Policy)

License

Public domain