labthings_fastapi.server.fallback

A fallback server for LabThings.

If the fallback option is given when labthings-server is run, we will still start an HTTP server even if we cannot run LabThings with the specified configuration. This means that something will still be viewable at the expected URL, which is helpful if LabThings is running as a service, or on embedded hardware.

Attributes

`LOGGER`
`_TEMPLATE_PATH`
`LAST_RESORT_PAGE`
`app`

Classes

`FallbackContext`	A dataclass to provide the context of the server failing to load.
`FallbackApp`	A basic FastAPI application to serve a LabThings error page.

Functions

`root`(→ fastapi.responses.HTMLResponse)	Display the LabThings error page.
`fallback_route`(→ bool)	Return True, this is a LabThings Fallback Server.
`_format_error_and_traceback`(→ tuple[str, str])	Format the error and traceback.
`redirect_to_root`(→ starlette.responses.RedirectResponse)	Redirect all paths on the server to the error page.

Module Contents

labthings_fastapi.server.fallback.LOGGER

labthings_fastapi.server.fallback._TEMPLATE_PATH

class labthings_fastapi.server.fallback.FallbackContext

A dataclass to provide the context of the server failing to load.

error: BaseException | None = None: The error caught when running uvicorn.run.

server: labthings_fastapi.server.ThingServer | None = None: The ThingServer that failed to start.

config: labthings_fastapi.server.config_model.ThingServerConfig | dict[str, Any] | None = None

The config used to set up the server.

This can be the ThingServerConfig, or the dict read from the JSON file.

log_history: str | None = None: Any logging history to show.

labthings_fastapi.server.fallback.LAST_RESORT_PAGE = Multiline-String

Show Value

"""
<html>
<head lang="en">
  <title>LabThings Internal Error</title>
</head>
<body>
  <h1>LabThings Internal Error</h1>
  <p>Couldn't start LabThings Server.</p>
  <p>A further error occurred when gathering context.</p>
</body>
"""

class labthings_fastapi.server.fallback.FallbackApp(*args: Any, **kwargs: Any)

Bases: fastapi.FastAPI

A basic FastAPI application to serve a LabThings error page.

Set up a simple error server.

This app is used to display a single page, which explains why the LabThings server cannot start.

Parameters:

*args – is passed to fastapi.FastAPI.__init__.
**kwargs – is passed to fastapi.FastAPI.__init__.

html_code = 500

set_context(context: FallbackContext) → None

Set the fallback runtime context.

This should be called exactly once during failure handling.

Parameters:: context – A FallbackContext object with the server, the captured error, the configuration, and log history.

set_template_str(template_str: str) → None

Compile and set a Jinja template from a string.

Parameters:

template_str –

A Jinja2 template string. The template should be self-contained and must not extend or include other templates. If customised, the template must handle the following template context variables (each may be None):

error_message (str | None): Error message to display, if any.
things (list[str] | None): Names of successfully loaded
things.
config (str | None): The server configuration.
traceback (str | None): Formatted error traceback.
logginginfo (str | None): Captured logging output.

fallback_page() → fastapi.responses.HTMLResponse

Generate the fallback page and return it as an HTMLResponse.

Returns:: The HTMLResponse for the fallback page.
Raises:: RuntimeError – if the fallback context was never set.

labthings_fastapi.server.fallback.app

async labthings_fastapi.server.fallback.root() → fastapi.responses.HTMLResponse

Display the LabThings error page.

Returns:: a response that serves the error as an HTML page.

async labthings_fastapi.server.fallback.fallback_route() → bool

Return True, this is a LabThings Fallback Server.

Use this to check over the API if this is a LabThings Fallback Server.

Returns:: returns True. This is a LabThings Fallback Server.

labthings_fastapi.server.fallback._format_error_and_traceback(context: FallbackContext) → tuple[str, str]

Format the error and traceback.

If the error was in lifespan causing Uvicorn to raise SystemExit(3) without a traceback. Try to extract the saved exception from the server.

:param context:The FallbackContext object with all fallback information.

Returns:: A tuple of error message and error traceback.

async labthings_fastapi.server.fallback.redirect_to_root(path: str) → starlette.responses.RedirectResponse

Redirect all paths on the server to the error page.

If any URL other than the error page is requested, this server will redirect it to the error page.

Parameters:: path – The path requested.
Returns:: a response redirecting to the error page.