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/external.rst
|
||||
admin/eotk.rst
|
||||
admin/redirector/index.rst
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue