docs(redirector): adds redirector docs
This commit is contained in:
parent
bda9e387c1
commit
cd81807339
6 changed files with 331 additions and 0 deletions
96
docs/admin/redirector/cli.rst
Normal file
96
docs/admin/redirector/cli.rst
Normal file
|
|
@ -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 <url>
|
||||||
|
|
||||||
|
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 <url>
|
||||||
|
|
||||||
|
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 <hash>
|
||||||
|
|
||||||
|
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 <ip>
|
||||||
|
|
||||||
|
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 <config>` 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`.
|
||||||
26
docs/admin/redirector/config.rst
Normal file
26
docs/admin/redirector/config.rst
Normal file
|
|
@ -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
|
||||||
7
docs/admin/redirector/dev.rst
Normal file
7
docs/admin/redirector/dev.rst
Normal file
|
|
@ -0,0 +1,7 @@
|
||||||
|
===================
|
||||||
|
Developer Reference
|
||||||
|
===================
|
||||||
|
|
||||||
|
.. automodule:: app
|
||||||
|
:members:
|
||||||
|
|
||||||
153
docs/admin/redirector/http.rst
Normal file
153
docs/admin/redirector/http.rst
Normal file
|
|
@ -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.
|
||||||
|
* - /<hash>
|
||||||
|
- 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.
|
||||||
|
|
||||||
|
/<hash>
|
||||||
|
^^^^^^^
|
||||||
|
|
||||||
|
Redirect to the original URL associated with the given hash.
|
||||||
|
|
||||||
|
- Method: GET
|
||||||
|
- URL: /<hash>
|
||||||
|
|
||||||
|
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=<api_key>
|
||||||
|
$ curl -X GET /link?url=<url>&type=<type>&key=<api_key>
|
||||||
|
$ curl -X POST -H "Authorization: Bearer <api_key>" -d '<data>' /updt
|
||||||
|
$ curl -X GET /<hash>
|
||||||
|
|
||||||
|
Note: Replace `<api_key>`, `<url>`, `<type>`, `<data>`, and `<hash_>` 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 <https://bypass.censorship.guide/>`_ 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.
|
||||||
48
docs/admin/redirector/index.rst
Normal file
48
docs/admin/redirector/index.rst
Normal file
|
|
@ -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 <install>`: Provides instructions for installing and setting up the Short Link Redirector application.
|
||||||
|
2. :doc:`Configuration <config>`: Explains the configuration options and how to customize the application's behavior.
|
||||||
|
3. :doc:`HTTP API Reference <http>`: Details the available HTTP API endpoints and their usage.
|
||||||
|
4. :doc:`Command-Line Interface (CLI) <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
|
||||||
|
|
@ -23,6 +23,7 @@ Documentation Home
|
||||||
admin/conf.rst
|
admin/conf.rst
|
||||||
admin/external.rst
|
admin/external.rst
|
||||||
admin/eotk.rst
|
admin/eotk.rst
|
||||||
|
admin/redirector/index.rst
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue