API reference

These classes and functions are available to extension modules by importing gmcapsule.

`Config`(config_path)	Server configuration.
`Capsule`(cfg)	Server instance.
`Cache`()	Response cache base class.
`Context`(cfg[, allow_extension_workers, ...])
`gemini.Request`([identity, scheme, hostname, ...])	Request received from a client.
`gemini.Identity`(cert)	Client certificate.

Classes

Config

class gmcapsule.Config(config_path)

Server configuration.

Parameters:: config_path (str) – Path of a config INI file to load.

ini

Contents of the config INI file. Extension modules can use this to access additional custom config parameters. See configparser for details.

Type:: configparser.ConfigParser

hostnames()

Returns:: All the configured hostnames. The first listed hostname is considered the default to be used when a hostname is not otherwise specified.
Return type:: list(str)

port()

Returns:: Listening IP port of the server.
Return type:: int

prefixed_sections(prefix)

Find all sections in the config INI file whose name begins with the given prefix.

Parameters:: prefix (str) – Name prefix, e.g., cgi..
Returns:: Mapping of section names (with the prefix removed) to the corresponding INI sections (configparser.SectionProxy). An empty dictionary is returned if there are no sections matching the prefix.
Return type:: dict

root_dir()

Returns:: Content root directory for serving static files. The hostname is always automatically appended to this as a subdirectory.
Return type:: pathlib.Path

section(name)

Find a section in the config INI file.

Parameters:: name (str) – Name of the section.
Returns:: INI section.
Return type:: configparser.SectionProxy
Raises:: KeyError – The section was not found.

Capsule

class gmcapsule.Capsule(cfg)

Server instance.

The server is initialized as specified in the configuration. Extension modules are loaded and initialized.

After constructing and setting up Capsule, call the run() method to begin accepting incoming connections.

Parameters:: cfg (Config) – Server configuration.

run(): Start worker threads and begin accepting incoming connections. The server will run until stopped with a KeyboardInterrupt (^C).

Cache

class gmcapsule.Cache

Response cache base class.

Derived classes are expected to override the save() and try_load() methods to save and load response content as appropriate.

The server will not try to load or save cached content when a request includes a query string or a client certificate is provided. When multiple Cache objects have been installed, the save/load operation is attempted on each in turn until one cache succeeds in saving or loading content.

Each server worker thread constructs their own Cache objects. If there is a shared backing store like a file system or a database, proper care should be taken to synchronize access to it from the Cache objects.

The mapping from URLs to cache paths is:

gemini://example.com/path/file.gmi
 ↓
/example.com/path/file.gmi

save(path, media_type, content)

Save content to the cache.

Parameters:

path (str) – URL path being loaded with the hostname prepended as the top-level directory.
media_type (str) – MIME type, e.g., “text/plain”.
content (bytes) – Content to save.

Returns:

True if successfully saved.

Return type:

bool

try_load(path)

Load content from the cache.

Parameters:: path (str) – URL path being loaded with the hostname prepended as the top-level directory.
Returns:: Content MIME type and data. Returns (None, None) if nothing is cached for the given path.
Return type:: tuple(str, bytes)

Context

class gmcapsule.Context(cfg, allow_extension_workers=False, handler_queue=None, response_queues=None)

add(path, entrypoint, hostname=None, protocol='gemini')

Register a URL entry point.

Extension modules must call this to become visible in the server’s path hierarchy. Entry points are looked up in the order the modules were loaded, with earlier modules getting precedence.

Parameters:

path (str) – URL path. Must begin with a slash (/). Asterisk wildcards (*) are supported. Note that if the path /* is registered, it will match any requested URL.
entrypoint (callable) – Function or other callable object that gets called when a request is processed with a matching URL path. A Request is passed in as the only argument.
hostname (str) – Hostname for the entry point. If omitted, the entry point applies to all configured hostnames.
protocol (str) – Protocol for the entry point.

add_cache(cache)

Install a cache.

All installed caches will attempt to save and load content until one succeeds. The caches installed first get precedence.

Parameters:: cache (Cache) – Cache instance.

add_protocol(scheme, handler)

Registers a new protocol handler.

Parameters:

scheme (str) – URL scheme of the protocol.
handler (callable) – Handler to be called when a request with the specified scheme is received. The handler must return the response to be sent to the client (bytes).

call_entrypoint(request)

Calls the registered entry point for a request.

Parameters:: request (Request) – Request object.
Returns:: (status, meta, body, cache). The type of body can be bytes, bytearray, or pathlib.Path. Returning a pathlib.Path means that the body will be read from the referenced file. The cache is None if the data was not read from a cache.
Return type:: tuple

is_background_work_allowed(): Determines whether extension modules are allowed to start workers.

shutdown_event()

Returns:: Extension modules must check this to be notified when the server is being shut down.
Return type:: threading.Event

Request

class gmcapsule.gemini.Request(identity=None, scheme='gemini', hostname='', path='', query=None, remote_address=None, content_token=None, content_mime=None, content=None, worker_id=None, is_titan_edit=False)

Request received from a client.

Request objects are used to pass information to entry points handlers. One does not need to construct them directly.

remote_address

IP address of the client.

Type:: str

scheme

Request protocol scheme. Either gemini or titan.

Type:: str

identity

Client certificate. May be None.

Type:: gmcapsule.gemini.Identity

hostname

Hostname.

Type:: str

path

URL path. Always begins with a /.

Type:: str

query

Encoded query string. You can use urllib.parse.unquote() to decode the percent-coding. None if the URL does not have a query string.

Type:: str

content_token

Encoded token specified in Titan URLs. May be None.

Type:: str

content_mime

MIME type specified in Titan URls. May be None.

Type:: str

content

Content uploaded by the client in a Titan request. May be None.

Type:: bytes

is_titan_edit

Is this a Titan edit request? Handler may need to activate an edit lock.

Type:: bool

Identity

class gmcapsule.gemini.Identity(cert)

Client certificate.

SHA-256 hashes are calculated automatically for the whole certificate and just for the public key.

cert

Certificate (DER format).

Type:: bytes

pubkey

Public key (DER format).

Type:: bytes

fp_cert

SHA-256 hash of the certificate.

Type:: str

fp_pubkey

SHA-256 hash of the public key.

Type:: str

issuer()

Returns:: Name components of the certificate issuer, e.g.: {'CN': 'Name'}.
Return type:: dict

subject()

Returns:: Name components of the certificate subject, e.g.: {'CN': 'Name'}.
Return type:: dict

Functions

gmcapsule.get_mime_type(path)

Determine the MIME type of a file. A handful of common file extensions are detected as special cases, such as “.gmi” and “.txt”. Other files are detected with Python’s mimetypes standard library module, and as a final fallback, the file command line utility.

Parameters:: path (str) – File path.
Returns:: Detected MIME type, for example, “image/jpeg”. Returns “application/octet-stream” if the correct type could not be determined.
Return type:: str

gmcapsule.markdown_to_gemini(src)

Convert a Markdown document to Gemtext. Only basic Markdown features are supported, such as headings, unordered and ordered lists (without changing any numbering present in the source), blockquotes, and paragraph and line breaks.

Parameters:: src (str) – Markdown source text.
Returns:: Corresponding text/gemini source.
Return type:: str