Coverage for gws-app/gws/base/web/__init__.py: 100%

1"""Web application, web site settings and assets. 

2 

3This package contains the WSGI application that serves all web requests, the 

4web site configuration and the ``web`` action for pages, assets and files. 

5 

6Submodules: 

7 

8- ``wsgi_main``: the WSGI entry point loaded by uWSGI. 

9- ``wsgi_app``: the WSGI application. It loads the configuration on the first 

10 request, then creates a requester for each request, runs the middleware and 

11 dispatches the command to an action. 

12- ``wsgi``: the requester (``gws.WebRequester``) and responder 

13 (``gws.WebResponder``) implementations, based on Werkzeug. 

14- ``error``: HTTP exceptions, and the conversion of GWS errors to HTTP errors. 

15- ``manager``: the web manager (``gws.WebManager``), configured in the ``web`` 

16 section of the application; it creates the web site. The ``ssl`` option of 

17 that section enables SSL for the site. 

18- ``site``: the web site (``gws.WebSite``): host names, SSL, CORS, security 

19 headers, static and assets directories, URL rewrite rules and URL generation. 

20- ``action``: the ``web`` action, which serves pages, assets, system assets 

21 (client scripts and styles), downloads and files stored in model fields. 

22 

23Requests 

24-------- 

25 

26The server handles requests to ``/_`` and ``/_/<command>``. Parameters of GET 

27requests are taken from the query string or from the path, in the form 

28``/_/<command>/<name1>/<value1>/<name2>/<value2>``. POST requests with a JSON or 

29MessagePack body are API requests; the response is encoded in the format of the 

30``Accept`` header, or else in the request format. Errors are converted to HTTP 

31errors; for API requests they are returned as a structured response, otherwise 

32the ``application.error`` template is rendered, if there is one. 

33 

34The rewrite rules of the site map incoming URLs to command URLs, and reversed 

35rules map generated command URLs back to readable ones. By default, ``/`` is the 

36application home page (``webPage`` with ``name=home``) and ``/project/<uid>`` 

37is the project page (``webPage`` with ``name=project``). The default rules are 

38added unless ``withDefaultRewriteRules`` is false or a configured rule has the 

39same pattern. Relative rewrite targets are made absolute. 

40 

41Assets 

42------ 

43 

44An asset is a file located in a global or project-specific assets directory. 

45If not configured, the global assets directory is ``/data/assets``, if it exists, 

46and the static root of the site is ``/data/web``, or a temporary directory if it 

47does not exist. 

48To access a project asset, the user must be allowed to use the project. When 

49the ``web`` action receives a ``webAsset`` request with a ``path`` argument, it 

50first checks the project assets directory, then the global one. 

51 

52If the file is found and its extension is one of 

53``gws.base.template.manager.TEMPLATE_TYPES``, a template is created from it on 

54the fly and rendered with ``gws.base.web.action.TemplateArgs``. The response of 

55the template is passed back to the user. Other files are returned as is if their 

56MIME type passes the ``allowMime`` and ``denyMime`` filters of the directory; 

57without ``allowMime``, only common web types (HTML, CSS, JavaScript, images, PDF, 

58JSON, XML and similar) are served. 

59 

60Example:: 

61 

62 { 

63 web.site { 

64 hostnames [ "maps.example.com" ] 

65 assets { dir "/data/assets" } 

66 rewriteRules [ 

67 { pattern "^/maps/([a-z0-9_]+)$" target "/_/webPage/name/project/projectUid/$1" } 

68 ] 

69 } 

70 actions [ 

71 { type "web" access "allow all" } 

72 ] 

73 } 

74""" 

75 

76from . import error, manager, site, wsgi