file.integration

Module Contents

Classes

DepotApp

Provides Depot integration for

Functions

configure_depot_tween_factory(...)
render_depot_file(→ webob.Response)
respond_with_alt_text(→ None)
respond_with_caching_header(→ None)
respond_with_x_robots_tag_header(→ None)
get_file(→ onegov.file.models.File | None)
view_file(→ depot.io.interfaces.StoredFile)
view_thumbnail(→ StoredFile | Response)
view_file_head(→ depot.io.interfaces.StoredFile)
view_thumbnail_head(→ StoredFile | Response)
handle_note_update(→ None)
handle_rename(→ None)
delete_file(→ None)	Deletes the given file. By default the permission is

Attributes

SUPPORTED_STORAGE_BACKENDS

file.integration.SUPPORTED_STORAGE_BACKENDS = ('depot.io.local.LocalFileStorage', 'depot.io.memory.MemoryFileStorage')

class file.integration.DepotApp

Bases: morepath.App

Provides Depot integration for onegov.core.framework.Framework based applications.

property bound_depot_id: str

property bound_depot: FileStorage | None

property bound_storage_path: pathlib.Path

property signing_service_id: str

property signing_service_config: onegov.file.types.SigningServiceConfig

property signing_service: onegov.file.sign.SigningService

custom_depot_id

configure_files(*, depot_backend: str | None = None, depot_storage_path: str | None = None, frontend_cache_buster: str | None = None, frontend_cache_bust_delay: int = 2, signing_services: str | None = None, **cfg: Any) → None

Configures the file/depot integration. The following configuration options are accepted:

Depot_backend:

The depot backend to use. Supported values:

• depot.io.local.LocalFileStorage

• depot.io.memory.MemoryFileStorage

Depot_storage_path:

The storage path used by the local file storage.

Note that the actual files are stored under a subdirectory specific to each application id. This is mainly to keep a handle on which file belongs to which application. Additionally it ensures that we aren’t accidentally opening another application’s files.

Frontend_cache_buster:

A script able to bust the frontend cache.

Our frontend (nginx) caches the files we store in the backend and serves them mostly without bothering us. This can be problematic when the file is deleted or if it is made private. The cache needs to be busted in this case.

With this configuration a script/command can be specified that receives the url that needs to be busted and in turn busts the content of this url from the cache. This pretty much depends on the platform this is run and on the frontend in use.

For example, let’s say our script is called ‘bust-cache’, this is the command that will be run when the cache is busted:

sleep 5
bust-cache id-of-the-file

As you can see, the command is invoked with a five second delay. This avoids premature cache busting (before the end of the transaction). The command is non-blocking, so those 5 seconds are not counted towards the request-time.

Frontend caches might use the domain and the full path to cache a file, but since we can technically have multiple domains/paths point to the same file we simply pass the id and let the cache figure out what urls need to be busted as a result.

The script is invoked with the permissions of the user running the backend. If other permissions are required, use suid.

Note that this script is optional. If omitted, the cache busting turns into a noop.

Signing_services:

Contains signing service configs.

Each application gets exactly one signing service.

This integration class will take care of instantiating the signing service and offer it through self.signing_service.

The signing service can be used with any file, though there is first-class support for signing onegov.file models.

Signing services are implemented using sublcasses of the onegov.file.sign.SigningService. Each signature service class is configured using a single yaml file which is stored in the signature config path.

By default we use the ‘__default__.yml’ config. Alternatively we can create separate configs for various application ids.

For example, we might create a onegov_town6-govikon.yml, which would take precedence over the default config, if the application with the id onegov_town6-govikon would use the signing service.

_configure_depot(backend: str | None, storage_path: str | None) → None

create_depot() → None

bind_depot() → None

bust_frontend_cache(file_id: str) → None

sign_file(file: onegov.file.models.File, signee: str, token: str, token_type: str = 'yubikey') → None

Signs the given file and stores metadata about that process.

During signing the stored file is replaced with the signed version.

For example:

pdf = app.sign_file(pdf, 'info@example.org', 'foo')

Parameters:

• file – The onegov.file..File instance to sign.

• signee – The name of the signee (should be a username).

• token –

  The (yubikey) token used to sign the file.

  WARNING: It is the job of the caller to ensure that the yubikey has the right to sign the document (i.e. that it is the right yubikey).

• token_type – They type of the passed token. Currently only ‘yubikey’.

clear_depot_cache() → None

temporary_depot(depot_id: str, *, depot_backend: str | None = None, depot_storage_path: str | None = None, **ignored: Any) → Iterator[None]

Temporarily use another depot.

file.integration.configure_depot_tween_factory(app: DepotApp, handler: Callable[[CoreRequest], Response]) → Callable[[CoreRequest], Response]

file.integration.render_depot_file(file: depot.io.interfaces.StoredFile, request: onegov.core.request.CoreRequest) → webob.Response

file.integration.respond_with_alt_text(reference: onegov.file.models.File, request: onegov.core.request.CoreRequest) → None

file.integration.respond_with_caching_header(reference: onegov.file.models.File, request: onegov.core.request.CoreRequest) → None

file.integration.respond_with_x_robots_tag_header(reference: onegov.file.models.File, request: onegov.core.request.CoreRequest) → None

file.integration.get_file(app: DepotApp, id: str) → onegov.file.models.File | None

file.integration.view_file(self: onegov.file.models.File, request: onegov.core.request.CoreRequest) → depot.io.interfaces.StoredFile

file.integration.view_thumbnail(self: onegov.file.models.File, request: onegov.core.request.CoreRequest) → StoredFile | Response

file.integration.view_file_head(self: onegov.file.models.File, request: onegov.core.request.CoreRequest) → depot.io.interfaces.StoredFile

file.integration.view_thumbnail_head(self: onegov.file.models.File, request: onegov.core.request.CoreRequest) → StoredFile | Response

file.integration.handle_note_update(self: onegov.file.models.File, request: onegov.core.request.CoreRequest) → None

file.integration.handle_rename(self: onegov.file.models.File, request: onegov.core.request.CoreRequest) → None

file.integration.delete_file(self: onegov.file.models.File, request: onegov.core.request.CoreRequest) → None

Deletes the given file. By default the permission is Private. An application using the framework can override this though.

Since a DELETE can only be sent through AJAX it is protected by the same-origin policy. That means that we don’t need to use any CSRF protection here.

That being said, browser bugs and future changes in the HTML standard make it possible for this to happen one day. Therefore, a time-limited token must be passed as query parameter to this function.

New tokens can be acquired through request.new_csrf_token.