Opinionated FaaS support framework extending Google's functions-framework
Project description
UCam FaaS Library
This project contains a support library and base Docker image to be used to create Function as a Service (FaaS) applications intended to be deployed to a GCP cloud run environment.
It is highly opinionated and non-configurable by design.
Usage
Install the library via pip:
pip install ucam-faas
Install the library with testing support:
pip install ucam-faas[testing]
The library provides a decorator to create a runnable application from a single function. The function must accept a dictionary as an argument, and return either a string or a dictionary as a response:
# main.py
from ucam_faas import event_handler
@event_handler
def say_hello(event):
return "hello!"
This can then be run as a FaaS app using:
ucam-faas --debug --target say_hello
Testing FaaS Functions
To unit test FaaS functions there are two available approaches. Firstly, the unwrapped version of the function can be directly accessed. This is recommended as the primary way to test FaaS functions and requires no additional configuration:
# test_my_event_handler.py
from main import say_hello
def test_say_hello():
assert say_hello.__wrapped__({"event_key": "event_value"}) == "hello!"
The original function version is made available through the __wrapped__
variable.
Alternatively, if required, a support testing client can be used to instantiate a version of the web application running the function. To do this the extra "testing" must also be installed:
pip install ucam-faas[testing]
Then tests can register the provided pytest
fixture and use it in tests:
# test_my_event_handler.py
pytest_plugins = ["ucam_faas.testing"]
def test_say_hello(event_app_client):
# Provide the target function for the test webapp
eac = event_app_client("say_hello")
response = eac.get("/")
assert response.status_code == 200
Note that with this approach it is not necessary to import the function under test, it is discovered and imported during the test webapp setup.
Example
An example application and example tests can be found in this repository in the
example
directory.
Note that the example dockerfile uses a relative file FROM
- this means it
must be built in the context of its parent directory:
docker build -f example/Dockerfile .
Local Development
Install poetry via:
pipx install poetry
pipx inject poetry poethepoet[poetry_plugin]
Install dependencies via:
poetry install
Build the library via:
poetry build
Run the example application via:
poetry poe example
Run the tests via:
poetry poe tox
Note that the tests are found under the example directory, there are currently no tests in the root library as the code is predominantly configuration and setup, and example testing has been deemed sufficient.
Dependencies
IMPORTANT: if you add a new dependency to the application as described below you will need to run
docker compose build
or add--build
to thedocker compose run
and/ordocker compose up
command at least once for changes to take effect when running code inside containers. The poe tasks have already got--build
appended to the command line.
To add a new dependency for the application itself:
poetry add {dependency}
To add a new development-time dependency used only when the application is running locally in development or in testing:
poetry add -G dev {dependency}
To remove a dependency which is no longer needed:
poetry remove {dependency}
CI configuration
The project is configured with Gitlab AutoDevOps via Gitlab CI using the .gitlab-ci.yml file.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for ucam_faas-0.6.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 82c48ac4ff418a164b80e3c03734f5a2f59af1ceeece4d054ad2d234f3d51956 |
|
MD5 | f07f943b50f7850ce9447560f044f4eb |
|
BLAKE2b-256 | ee1f1a7f732532a99823ff0f947d2ad2ee903bea2ff8871c425703f8acb19c63 |