book_server_api.routers.books module

Overview

This module contains the router for serving pages from a book. It also contains the code for serving the library page.

The following routes are defined:

  • /published/<book_name>/<page_name> - Serve a page from a book

  • /index/<book_name>/ - Serve the library page

Detailed Module Description

book_server_api.routers.books.URL(*argv)
book_server_api.routers.books.XML(arg)
async book_server_api.routers.books.crashme()
async book_server_api.routers.books.fetch_subchaptoc(course: str, chap: str)
async book_server_api.routers.books.get_downloads(course: str, filepath: str)
async book_server_api.routers.books.get_external(course: str, filepath: str)
async book_server_api.routers.books.get_generated(course: str, filepath: str)
async book_server_api.routers.books.get_image(course: str, filepath: str)
async book_server_api.routers.books.get_jlite(course: str, filepath: str)
async book_server_api.routers.books.get_ptximages(course: str, filepath: str)
async book_server_api.routers.books.get_static(course: str, filepath: str)
async book_server_api.routers.books.library(request: ~starlette.requests.Request, response_class=<class 'starlette.responses.HTMLResponse'>)

Create the library page from the Library database table.

Parameters:

  • request (Request) – The FastAPI request object.

  • response_class (_type_, optional) – defaults to HTMLResponse

Returns:

HTMLResponse

Return type:

HTMLResponse

async book_server_api.routers.books.return_static_asset(course: str, kind: str, filepath: str)

Return a static asset from a book. These are typically images, css, or js files. they do not require any special processing or use of templates.

Parameters:

  • course (str) – The name of the course

  • kind (str) – What kind of assset is it?

  • filepath (str) – The path to the file

Raises:

HTTPException –

Returns:

Response object

book_server_api.routers.books.safe_join(directory, *pathnames)

Safely join directory and one or more untrusted pathnames. If this cannot be done, this function returns None. The main thing this does is make sure that we do not allow relative pathnames going up the directory tree to be joined to the base directory. This is important because it prevents an attacker from using a pathname like ../../../etc/passwd to read an arbitrary file on the server filesystem.

Parameters:

  • directory – the base directory.

  • pathnames – the untrusted pathnames relative to that directory.

Returns:

the joined path or None if this cannot be done.

async book_server_api.routers.books.serve_page(request: Request, course_name: str, pagepath: str, RS_info: Optional[str] = Cookie(None), mode: Optional[str] = None)

Serve a page from a book.

Book pages are not static, they are generated on the fly. When you build a book, ptx or runestone bulds the pages of the book as Jinja2 templates. This endpoint serves those pages by gathering data from the database and passing it to the template. Some key parts of the template include:

  • course attributes

  • user information

  • whether to serve an ad or not

  • whether to ask for a donation or not

  • the subchapter navigation menu

  • the page content

Note

Caution Anyone modifying this function should exercise caution. It is the core of the Runestone server and is used by all books. It is called hundreds of thousands of times a day so performance is critical.

Parameters:

  • request (Request) – A FastAPI request object

  • course_name (constr, optional) – The name of the course (part of the URL)

  • pagepath (constr, optional) – The path to the page (part of the URL)

  • RS_info (Optional[str], optional) – An RS_info cookie, defaults to None

  • mode (Optional[str], optional) – _description_, defaults to None

Raises:

HTTPException – _description_

Returns:

response object

Return type:

Response