From cd818073397b541c53899f1b15960f86dd163bec Mon Sep 17 00:00:00 2001 From: Iain Learmonth Date: Sun, 25 Jun 2023 13:27:08 +0100 Subject: [PATCH] docs(redirector): adds redirector docs --- docs/admin/redirector/cli.rst | 96 +++++++++++++++++++ docs/admin/redirector/config.rst | 26 ++++++ docs/admin/redirector/dev.rst | 7 ++ docs/admin/redirector/http.rst | 153 +++++++++++++++++++++++++++++++ docs/admin/redirector/index.rst | 48 ++++++++++ docs/index.rst | 1 + 6 files changed, 331 insertions(+) create mode 100644 docs/admin/redirector/cli.rst create mode 100644 docs/admin/redirector/config.rst create mode 100644 docs/admin/redirector/dev.rst create mode 100644 docs/admin/redirector/http.rst create mode 100644 docs/admin/redirector/index.rst diff --git a/docs/admin/redirector/cli.rst b/docs/admin/redirector/cli.rst new file mode 100644 index 0000000..0ac1e94 --- /dev/null +++ b/docs/admin/redirector/cli.rst @@ -0,0 +1,96 @@ +=============== +CLI Interface +=============== + +Introduction +------------ + +The CLI interface provides command-line tools for manual short link administration. These tools allow users to perform various operations, such as generating short links, resolving short links, and looking up country information using GeoIP. + +Available Commands +------------------ + +The following commands are available in the CLI: + +.. list-table:: + :header-rows: 1 + + * - Command + - Description + * - short + - Generate a short link. + * - direct + - Generate a direct mirror link. + * - resolve + - Resolve a short link to a mirror link. + * - geoip + - Look up the country name for an IP address. + +Command: short +^^^^^^^^^^^^^ + +Generate a short link. + +Command Usage: + +.. code-block:: shell + + $ link short + +Arguments: +- `url` (required): The URL for which a short link needs to be generated. + +Command: direct +^^^^^^^^^^^^^^ + +Generate a direct mirror link. + +Command Usage: + +.. code-block:: shell + + $ link direct + +Arguments: +- `url` (required): The URL for which a direct mirror link needs to be generated. + +Command: resolve +^^^^^^^^^^^^^^^^ + +Resolve a short link to a mirror link. + +Command Usage: + +.. code-block:: shell + + $ link resolve + +Arguments: +- `hash` (required): The hash associated with the short link. + +Command: geoip +^^^^^^^^^^^^^^ + +Look up the country name for an IP address. + +Command Usage: + +.. code-block:: shell + + $ link geoip + +Arguments: +- `ip` (required): The IP address for which the country name needs to be looked up. + +Configuration +------------- + +The CLI interface uses the application's configuration file to load settings and defaults. See :doc:`configuration file ` for more information. + +Environment Variables +--------------------- + +The application supports the following environment variables to configure its behavior: + +- `REDIRECTOR_BASE_URL`: The base URL used for generating short links and direct mirror links. If not set, it defaults to `http://127.0.0.1:5000/`. +- `REDIRECTOR_API_KEY`: The API key used for generating short links and direct mirror links. If not set, it defaults to `None`. diff --git a/docs/admin/redirector/config.rst b/docs/admin/redirector/config.rst new file mode 100644 index 0000000..6b53c88 --- /dev/null +++ b/docs/admin/redirector/config.rst @@ -0,0 +1,26 @@ +================== +Configuration File +================== + +The application uses a YAML configuration file to specify various settings. The configuration file should follow the YAML syntax and provide values for the following fields: + +- `DEFAULT_REDIRECTOR_DOMAIN`: The default domain name to use for generating short links when no pool-specific redirector domain is provided. If not specified, it defaults to an empty string. +- `MIRROR_COUNTRIES`: A list of country codes for which clients should be redirected to a mirror server. If a client's IP address matches one of the specified countries, they will be redirected. If not specified, clients will always be redirected to a mirror server. +- `PUBLIC_KEY`: The public API key used for generating short links for anonymous users. If not specified, it defaults to an empty string. +- `UPDATE_KEY`: The API key required for updating the application data via the `/updt` endpoint. This key must be provided in the `Authorization` header as a bearer token. +- `GEOIP_DATABASE` (optional): The file path to the GeoIP database used for country lookup. If not specified, it defaults to `/usr/share/GeoIP/GeoIP2-Country.mmdb`. + +Example Configuration +--------------------- + +An example configuration file may look like this: + +.. code-block:: yaml + + DEFAULT_REDIRECTOR_DOMAIN: example.com + MIRROR_COUNTRIES: + - US + - CA + - GB + PUBLIC_KEY: public_key + GEOIP_DATABASE: /path/to/geoip/database.mmdb \ No newline at end of file diff --git a/docs/admin/redirector/dev.rst b/docs/admin/redirector/dev.rst new file mode 100644 index 0000000..a489ef5 --- /dev/null +++ b/docs/admin/redirector/dev.rst @@ -0,0 +1,7 @@ +=================== +Developer Reference +=================== + +.. automodule:: app + :members: + diff --git a/docs/admin/redirector/http.rst b/docs/admin/redirector/http.rst new file mode 100644 index 0000000..9f7db41 --- /dev/null +++ b/docs/admin/redirector/http.rst @@ -0,0 +1,153 @@ +============ +HTTP API +============ + +Introduction +------------ + +The HTTP API allows clients to interact with the application and perform various operations related to short links and mirrors. The API supports the following endpoints: + +.. list-table:: + :header-rows: 1 + + * - Endpoint + - Method + - Description + * - /me + - GET + - Retrieve information about the authenticated user's pool. + * - /link + - GET + - Generate a short link or a direct mirror link. + * - /updt + - POST + - Update the application's data. + * - / + - GET + - Redirect to the original URL associated with the given hash. + +Authentication +-------------- + +The API endpoints are protected by authentication. The authentication method depends on the endpoint: + +- /me endpoint: The API key is provided in the request arguments using the `key` parameter. If no API key is provided, the "public" resource pool is used. +- /link endpoint: The API key is provided in the request arguments using the `key` parameter. If no API key is provided, the "public" resource pool is used. +- /updt endpoint: The API key is sent in the `Authorization` header as a bearer token. + +Endpoints +--------- + +/me +^^^^^^ + +Retrieve information about the authenticated user's pool. + +- Method: GET +- URL: /me + +Query Parameters: + +- `key` (optional): The API key of the pool. If not provided, the public API key is used. + +Response: + +- Success: Returns the information about the pool in JSON format. +- Failure: Returns a 403 response if the API key is invalid. + +/link +^^^^^ + +Generate a short link or a direct mirror link. + +- Method: GET +- URL: /link + +Query Parameters: + +- `url` (required): The URL for which a link needs to be generated. +- `type` (optional): The type of link to generate. Valid values are "direct" or "short". If not provided, "direct" is used. +- `key` (optional): The API key of the pool. If not provided, the public API key is used. + +Response: + +- Success: Returns the generated link in JSON format. +- Failure: Returns a 404 response if a link could not be generated. + +/updt +^^^^^ + +Update the application's data. + +- Method: POST +- URL: /updt + +Headers: + +- `Authorization`: The API key as a bearer token. + +Request Body: + +- The updated data in JSON format. + +Response: + +- Success: Returns a JSON response indicating the update was successful. +- Failure: Returns a 403 response if the API key is invalid. + +/ +^^^^^^^ + +Redirect to the original URL associated with the given hash. + +- Method: GET +- URL: / + +Path Parameters: + +- `hash` (required): The hash associated with the short link. + +Query Parameters: + +- `force` (optional): Always redirect to a mirror and ignore GeoIP information. +- `force_ip` (optional): Override the client IP address and base the GeoIP lookup on this IP address instead. + +Response: + +- Success: Redirects the client to the original URL. +- Failure: Returns a 404 response if the hash is invalid or not found. + +Example Usage +------------- + +.. code-block:: bash + + $ curl -X GET /me?key= + $ curl -X GET /link?url=&type=&key= + $ curl -X POST -H "Authorization: Bearer " -d '' /updt + $ curl -X GET / + +Note: Replace ``, ``, ``, ``, and `` with actual values. + +Authentication and Permissions +------------------------------- + +The API endpoints require valid API keys for authentication. The API key can be obtained from the pool configuration. + +API keys have different permissions: + +- Public API Key: Can be used to access direct mirror links and resolve short links. +- Private API Key: Can be used to access read-only endpoints and create new short links. +- Update API Key: Can be used to update the mirror list data. + +Please refer to the `pool configuration `_ documentation for more information on managing resource pool API keys. + +Response Format +--------------- + +The API endpoints generally return JSON responses. Successful responses contain the requested data, while failure responses provide relevant error messages. + +Error Handling +-------------- + +In case of errors, the API endpoints return appropriate HTTP status codes and error messages. Clients should handle these errors gracefully and take appropriate actions. diff --git a/docs/admin/redirector/index.rst b/docs/admin/redirector/index.rst new file mode 100644 index 0000000..87ddf34 --- /dev/null +++ b/docs/admin/redirector/index.rst @@ -0,0 +1,48 @@ +===================== +Short Link Redirector +===================== + +Welcome to the documentation for the *Bypass Censorship's Short Link Redirector* application. This documentation provides detailed information about the features, components, and usage of the application. The Short Link Redirector is a web application that allows users to generate short links and direct mirror links for URLs. + +Features +-------- + +The Short Link Redirector application offers the following features: + +- Short Link Generation: Users can generate short links for URLs, making them easier to share and remember. +- Direct Mirror Links: Users can generate and discover direct mirror links that are currently live. +- Country-based Redirect: The application can redirect users to mirror servers based on their country, improving user experience. +- API Key Authentication: Users can authenticate their requests using API keys, enabling access to mirrors in private resource pools. +- GeoIP Integration: The application optionally leverages GeoIP data to perform country lookups for IP addresses. + +Components +---------- + +The Short Link Redirector application consists of the following main components: + +- Flask Web Server: The web server that hosts the application and handles incoming HTTP requests. +- SQLAlchemy: The ORM (Object-Relational Mapping) library used for interacting with the database. +- GeoIP Database: The MaxMind GeoIP database that provides country information for IP addresses. +- Hashids: The library used for encoding and decoding the short link hashes. + +Documentation Structure +----------------------- + +This documentation is structured into the following sections: + +1. :doc:`Installation `: Provides instructions for installing and setting up the Short Link Redirector application. +2. :doc:`Configuration `: Explains the configuration options and how to customize the application's behavior. +3. :doc:`HTTP API Reference `: Details the available HTTP API endpoints and their usage. +4. :doc:`Command-Line Interface (CLI) `: Describes the command-line interface commands and their functionality. + +We recommend reading through the documentation sequentially to gain a comprehensive understanding of the application and its features. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + :hidden: + + install + config + http + cli diff --git a/docs/index.rst b/docs/index.rst index 0b1028e..f4527b0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -23,6 +23,7 @@ Documentation Home admin/conf.rst admin/external.rst admin/eotk.rst + admin/redirector/index.rst .. toctree:: :maxdepth: 2