DOCSEARCHbyAlgolia
Submit Docs

WsgiDAV Documentation

repository·master·Indexed 22 days ago

https://github.com/mar10/wsgidav

A generic, extendable WebDAV server written in Python based on the WSGI protocol. WsgiDAV can operate as a standalone server or be integrated into WSGI-compliant web servers as middleware. It supports various resource providers, including filesystem, MySQL, and Mercurial, and offers flexible authentication via Data Connectors (DC) and property management through backends like MongoDB and CouchDB.

Tokens
11.4K
Snippets
32
Records
74
Agent score
78%

What's inside WsgiDAV

  1. What is WsgiDAV?

    master

    WsgiDAV is a generic and extendable WebDAV server written in Python. It is based on the WSGI protocol and can be used in two primary ways:

    1. As a standalone server: Run it as a Python command-line script with SSL support.
    2. As a Python library: Integrate it into any WSGI-compliant web server as a configurable stack of WSGI middleware applications.

    Typical use cases include exposing data structures as virtual, editable file systems or allowing online editing of MS Office documents.

  2. Overview of WsgiDAV core packages

    master

    WsgiDAV is organized into several functional packages that handle different aspects of the WebDAV protocol and server implementation:

    • wsgidav: The core package containing fundamental components like dav_provider, fs_dav_provider (filesystem provider), http_authenticator, and the main wsgidav_app.
    • wsgidav.dc: Contains Data Connectors (DC) for authentication and user management, such as simple_dc, nt_dc, and pam_dc.
    • wsgidav.mw: Contains Middleware (MW) components like base_mw, cors, and debug_filter to extend server functionality.
    • wsgidav.prop_man: Manages WebDAV properties using different backends like property_manager, couch_property_manager, or mongo_property_manager.
    • wsgidav.lock_man: Handles WebDAV locking mechanisms via lock_manager and lock_storage.
    • wsgidav.server: Provides server execution components including server_cli, run_reloading_server, and various server samples.

  3. Explore WsgiDAV Samples and Addons

    master

    WsgiDAV provides several sample implementations and addons that extend its functionality. These include specialized WebDAV providers, authentication domain controllers, and property managers.

    Available addon types include:

    • WebDAV Providers: Implementations that publish specific data sources like Mercurial repositories, MongoDB databases, MySQL databases (read-only emulation), or Google App Engine's Bigtable via CloudDAV.
    • Domain Controllers: Implementations like addons-ntdc that allow authentication against a Windows NT domain or a local computer.
    • Property Managers: Implementations like addons-mongo-propman (MongoDB) or addons-couch-propman (CouchDB) used to store 'dead properties' for WebDAV providers.

  4. Understand the Mercurial WebDAV repository structure

    master

    The Mercurial WebDAV provider renders a repository as three distinct top-level collections. This structure dictates how you interact with the version control system via WebDAV:

    1. edit/: Contains the working directory (all files, including uncommitted changes and untracked files). This folder is writable.
    2. released/: Contains the latest committed files (the 'tip'). This folder is read-only.
    3. archive/: Contains the last 10 revisions as sub-folders. This folder is read-only.

    Sample Layout

    /<share>/
    edit/
        server/
            ext_server.py
        README.txt
    released/
    archive/
        19/
        18/
        ...

  5. WsgiDAV Preconditions and Requirements

    master

    To run WsgiDAV, ensure the following requirements are met:

    • Python: Version 3.6 or later.
    • WSGI Server: WsgiDAV is a WSGI application and requires a compliant web server to run. Recommended servers include:
      • Cheroot (recommended for performance and stability)
      • gevent
      • Gunicorn
      • Uvicorn
      • wsgiref
    • Optional Dependency: lxml can be installed to improve the performance of PROPPATCH requests by up to 10%.

  6. Understand Reference URLs and Virtual Locations

    master

    A reference URL is a quoted, UTF-8 encoded byte string used as a unique key for lock and property storage.

    While a resource has one 'real location', it may have multiple 'virtual locations' (e.g., via keys or status-based paths). The reference URL is the unique identifier that maps all these locations to the same resource. It is constructed as realUrl = quote(mount_path + reference path).

  8. Understand WsgiDAV URL and Path terminology

    master

    WsgiDAV distinguishes between several types of URLs and paths. Understanding these is critical when working with WsgiDAV variables or implementing providers:

    • URL: Byte strings using ISO-8859-1 encoding. They are case-sensitive and quoted (special characters are escaped). Collections should have a trailing /.
      • Absolute URL: Typically follows the pattern /<mount>/<path>.
      • Full URL: The complete URL including scheme and host, e.g., http://<server>:<port>/<mount>/<path>. Use util.makeCompleteURL(environ) to construct this.
    • Path: Generally refers to unquoted URLs relative to the mount point (e.g., /public/my nice doc.txt).
    • href: A quoted, UTF-8 encoded byte string used in XML responses. It is path-absolute (starts with /). It is constructed as quote(mount_path + preferred_path).

  9. Identify Mount Points and Share Paths

    master

    WsgiDAV uses specific terms to describe where the application is located within a web server hierarchy:

    • mount point (also 'mount path', 'approot'): The virtual directory where the web server mounted the WsgiDAV application. It is the environ[SCRIPT_NAME] set by the WSGI server. It is an unquoted, ISO-8859-1 encoded byte string starting with /.
    • share path (also 'share', 'domain'): The application's share path relative to the mount point. It represents the common URL prefix for the registered provider found for a request. It is constructed via share_path = environ[SCRIPT_NAME].

  10. Understand the WsgiDAV Application Stack

    master

    WsgiDAV is a WSGI application composed of a container (WsgiDavApp), several middleware layers, and a core application (RequestServer).

    By default, the stack follows this order:

    1. wsgidav_app.WsgiDavApp (The container)
    2. debug_filter.WsgiDavDebugFilter (Optional middleware)
    3. error_printer.ErrorPrinter (Middleware)
    4. http_authenticator.HTTPAuthenticator (Middleware, uses a Domain Controller)
    5. dir_browser.WsgiDavDirBrowser (Optional middleware)
    6. request_resolver.RequestResolver (Middleware)
    7. request_server.RequestServer (The core application, uses a DAV Provider, Lock Manager, and Property Manager)

    You can customize the middleware order or add your own middleware using the middleware_stack configuration option.

  11. Configure the Middleware Stack

    master

    WsgiDAV is a WSGI application extended by a list of middleware components. The stack is defined via the middleware_stack key in the configuration.

    Python Configuration

    You can pass instantiated middleware objects or the middleware classes themselves. If you pass a class, WsgiDAV will instantiate it using a common signature. Built-in middleware includes WsgiDavDebugFilter, ErrorPrinter, HTTPAuthenticator, WsgiDavDirBrowser, and RequestResolver. Note: RequestResolver must be the last item in the stack.

    YAML Configuration

    In YAML, you can specify middleware using their class paths. For third-party middleware where the constructor signature is not standard, use class with args (positional) or kwargs (named) keys. Use the special placeholder ${application} to refer to the WsgiDAV application instance.

    middleware_stack:
    - class: dozer.Dozer
      args:
        - "${application}"
    - class: dozer.Profiler
      args:
        - "${application}"
        - null  # global_conf
        - /tmp  # profile_path
    - wsgidav.mw.debug_filter.WsgiDavDebugFilter
    - wsgidav.error_printer.ErrorPrinter
    - wsgidav.http_authenticator.HTTPAuthenticator
    - wsgidav.dir_browser.WsgiDavDirBrowser
    - wsgidav.request_resolver.RequestResolver