From af0458d42d1a6dccea3335afbfaf9e774a8550ff Mon Sep 17 00:00:00 2001 From: Daniil Gentili Date: Sat, 1 Jun 2019 14:03:34 +0200 Subject: [PATCH] Write new proxy docs --- docs/docs/INSTALLATION.md | 9 +- docs/docs/PROXY.md | 242 ++++++++++++++++++++------------------ docs/docs/SETTINGS.md | 8 +- 3 files changed, 134 insertions(+), 125 deletions(-) diff --git a/docs/docs/INSTALLATION.md b/docs/docs/INSTALLATION.md index ea2eb888..0f35d928 100644 --- a/docs/docs/INSTALLATION.md +++ b/docs/docs/INSTALLATION.md @@ -44,9 +44,6 @@ composer.json: "type": "project", "require": { "danog/madelineproto": "dev-master", - "amphp/dns": "dev-master#861cc857b1ba6e02e8a7439c30403682785fce96 as 0.9.9", - "amphp/file": "dev-master#5a69fca406ac5fd220de0aa68c887bc8046eb93c as 0.3.3", - "amphp/uri": "dev-master#f3195b163275383909ded7770a11d8eb865cbc86 as 0.1.3" }, "repositories": [ { @@ -104,10 +101,6 @@ Then you can require the package by addding the following lines to the require s ``` "danog/madelineproto":"dev-master", -"amphp/dns": "dev-master#861cc857b1ba6e02e8a7439c30403682785fce96 as 0.9.9", -"amphp/file": "dev-master#5a69fca406ac5fd220de0aa68c887bc8046eb93c as 0.3.3", -"amphp/uri": "dev-master#f3195b163275383909ded7770a11d8eb865cbc86 as 0.1.3" - ``` -Next section \ No newline at end of file +Next section diff --git a/docs/docs/PROXY.md b/docs/docs/PROXY.md index 71397658..057f2df9 100644 --- a/docs/docs/PROXY.md +++ b/docs/docs/PROXY.md @@ -7,20 +7,115 @@ image: https://docs.madelineproto.xyz/favicons/android-chrome-256x256.png You can use a proxy with MadelineProto. -There are three ways to do this: - +* [How to set a proxy](#how-to-set-a-proxy) +* [Multiple proxies with automatic switch](#multiple-proxies-with-automatic-switch) +* [Use pre-built MTProxy](#mtproxy) * [Use pre-built Socks5 proxy](#socks5-proxy) * [Use pre-built HTTP proxy](#http-proxy) * [Build your own proxy](#build-your-proxy) +## How to set a proxy + +In order to set a proxy for MadelineProto, you have to modify the [settings](SETTINGS.html). +Legacy proxy names are allowed (`\HttpProxy`, `\SocksProxy`), but not recommended. +The recommended way of getting proxy names to set in the settings is through the `getName` method of the new [proxy interface](#build-your-proxy). + +```php +use danog\MadelineProto\Stream\MTProtoTransport\ObfuscatedStream; +use danog\MadelineProto\Stream\Proxy\HttpProxy; +use danog\MadelineProto\Stream\Proxy\SocksProxy; +use my\Custom\Namespace\MyProxy; + +$settings['connection_settings']['all']['proxy'] = ObfuscatedStream::getName(); +// ... +$settings['connection_settings']['all']['proxy'] = HttpProxy::getName(); +// ... +$settings['connection_settings']['all']['proxy'] = SocksProxy::getName(); +// ... +$settings['connection_settings']['all']['proxy'] = MyProxy::getName(); +``` + +You can also set multiple proxies: + +## Multiple proxies with automatic switch + +To set multiple proxies, and let MadelineProto choose the best one, simply assign arrays of proxy and proxy extras to the appropriate settings. +You can also use [iterable objects](https://www.php.net/manual/en/class.iterator.php) instead of arrays of proxy settings to dynamically change the proxies used without reloading the settings. + +```php +use danog\MadelineProto\Stream\MTProtoTransport\ObfuscatedStream; +use danog\MadelineProto\Stream\Proxy\HttpProxy; +use danog\MadelineProto\Stream\Proxy\SocksProxy; +use my\Custom\Namespace\MyProxy; + +$settings['connection_settings']['all']['proxy'] = [ + ObfuscatedStream::getName(), + ObfuscatedStream::getName(), + HttpProxy::getName(), + SocksProxy::getName(), + MyProxy::getName() +]; +$settings['connection_settings']['all']['proxy_extra'] = [ + [ + 'address' => 'magtg.com', + 'port' => 443, + 'secret' => 'dd.....' + ], + [ + 'address' => '1.2.3.4', + 'port' => 443, + 'secret' => 'dd.....' + ], + [ + 'address' => '0.0.0.0', + 'port' => 80, + 'username' => 'user', + 'password' => 'pass' + ], + [ + 'address' => '0.0.0.0', + 'port' => 242, + 'username' => 'user', + 'password' => 'pass' + ], + [ + 'address' => '0.0.0.0', + 'port' => 242, + 'custom' => 'args', + ], +]; +``` + +## MTProxy + +```php +use danog\MadelineProto\Stream\MTProtoTransport\ObfuscatedStream; + +$settings['connection_settings']['all']['proxy'] = ObfuscatedStream::getName(); +$settings['connection_settings']['all']['proxy_extra'] = [ + 'address' => '0.0.0.0', + 'port' => 443, + 'secret' => 'dd.....' +]; + +$MadelineProto = new \danog\MadelineProto\API('session.madeline', $settings); +``` + +Both normal and `dd` secrets are supported, the transport is changed automatically by MadelineProto. + ## Socks5 proxy No password: ```php -$settings['connection_settings']['all']['proxy'] = '\SocksProxy'; -$settings['connection_settings']['all']['proxy_extra'] = ['address' => $proxy_address, 'port' => $proxy_port]; +use danog\MadelineProto\Stream\Proxy\SocksProxy; + +$settings['connection_settings']['all']['proxy'] = SocksProxy::getName(); +$settings['connection_settings']['all']['proxy_extra'] = [ + 'address' => '0.0.0.0', + 'port' => 2343, +]; $MadelineProto = new \danog\MadelineProto\API('session.madeline', $settings); ``` @@ -29,8 +124,15 @@ $MadelineProto = new \danog\MadelineProto\API('session.madeline', $settings); With password: ```php -$settings['connection_settings']['all']['proxy'] = '\SocksProxy'; -$settings['connection_settings']['all']['proxy_extra'] = ['address' => $proxy_address, 'port' => $proxy_port, 'username' => 'user', 'password' => 'afnjasf']; +use danog\MadelineProto\Stream\Proxy\SocksProxy; + +$settings['connection_settings']['all']['proxy'] = SocksProxy::getName(); +$settings['connection_settings']['all']['proxy_extra'] = [ + 'address' => '0.0.0.0', + 'port' => 2343, + 'username' => 'username', + 'password' => 'password', +]; $MadelineProto = new \danog\MadelineProto\API('session.madeline', $settings); ``` @@ -40,8 +142,13 @@ $MadelineProto = new \danog\MadelineProto\API('session.madeline', $settings); No password: ```php -$settings['connection_settings']['all']['proxy'] = '\HttpProxy'; -$settings['connection_settings']['all']['proxy_extra'] = ['address' => $proxy_address, 'port' => $proxy_port]; +use danog\MadelineProto\Stream\Proxy\HttpProxy; + +$settings['connection_settings']['all']['proxy'] = HttpProxy::getName(); +$settings['connection_settings']['all']['proxy_extra'] = [ + 'address' => '0.0.0.0', + 'port' => 2343, +]; $MadelineProto = new \danog\MadelineProto\API('session.madeline', $settings); ``` @@ -50,8 +157,15 @@ $MadelineProto = new \danog\MadelineProto\API('session.madeline', $settings); With password: ```php -$settings['connection_settings']['all']['proxy'] = '\HttpProxy'; -$settings['connection_settings']['all']['proxy_extra'] = ['address' => $proxy_address, 'port' => $proxy_port, 'username' => 'user', 'password' => 'afnjasf']; +use danog\MadelineProto\Stream\Proxy\HttpProxy; + +$settings['connection_settings']['all']['proxy'] = HttpProxy::getName(); +$settings['connection_settings']['all']['proxy_extra'] = [ + 'address' => '0.0.0.0', + 'port' => 2343, + 'username' => 'username', + 'password' => 'password', +]; $MadelineProto = new \danog\MadelineProto\API('session.madeline', $settings); ``` @@ -59,111 +173,9 @@ $MadelineProto = new \danog\MadelineProto\API('session.madeline', $settings); ## Build your proxy -```php -class MyProxy implements \danog\MadelineProto\Proxy -{ - //... -} -$MadelineProto->settings['connection_settings']['all']['proxy'] = '\MyProxy'; -``` +In order to build your proxy, you have to use the new MadelineProto stream API to create your own proxy class. +Feel free to study [existing proxies](https://github.com/danog/MadelineProto/tree/master/src/danog/MadelineProto/Stream/Proxy) and the [stream API](https://github.com/danog/MadelineProto/tree/master/src/danog/MadelineProto/Stream): it's well structured and well documented, so feel free to read the code. +Don't forget to add support for [TLS connections](https://github.com/danog/MadelineProto/blob/master/src/danog/MadelineProto/Stream/Proxy/SocksProxy.php#L141) as well! -Simply create a class that implements the `\danog\MadelineProto\Proxy` interface, and enter its name in the settings. - -Your proxy class MUST use the `\Socket` class for all TCP/UDP communications. - -Your proxy class can also have a setExtra method that accepts an array as the first parameter, to pass the values provided in the proxy_extra setting. - -The `\Socket` class has the following methods (all of the following methods must also be implemented by your proxy class): - - -`public function __construct(int $domain, int $type, int $protocol);` - -Works exactly like the [socket_connect](http://php.net/manual/en/function.socket-connect.php) function. - - - -`public function setOption(int $level, int $name, $value);` - -Works exactly like the [socket_set_option](http://php.net/manual/en/function.socket-set-option.php) function. - - - -`public function getOption(int $name, $value);` - -Works exactly like the [socket_get_option](http://php.net/manual/en/function.socket-get-option.php) function. - - - -`public function setBlocking(bool $blocking);` - -Works like the [socket_block](http://php.net/manual/en/function.socket-set-block.php) or [socket_nonblock](http://php.net/manual/en/function.socket-set-nonblock.php) functions. - - - -`public function bind(string $address, [ int $port = 0 ]);` - -Works exactly like the [socket_bind](http://php.net/manual/en/function.socket-bind.php) function. - - - -`public function listen([ int $backlog = 0 ]);` - -Works exactly like the [socket_listen](http://php.net/manual/en/function.socket-listen.php) function. - - - -`public function accept();` - -Works exactly like the [socket_accept](http://php.net/manual/en/function.socket-accept.php) function. - - - -`public function connect(string $address, [ int $port = 0 ]);` - -Works exactly like the [socket_accept](http://php.net/manual/en/function.socket-connect.php) function. - - - - -`public function read(int $length, [ int $flags = 0 ]);` - -Works exactly like the [socket_read](http://php.net/manual/en/function.socket-read.php) function. - - - -`public function write(string $buffer, [ int $length ]);` - -Works exactly like the [socket_write](http://php.net/manual/en/function.socket-write.php) function. - - - -`public function send(string $data, int $length, int $flags);` - -Works exactly like the [socket_send](http://php.net/manual/en/function.socket-send.php) function. - - - -`public function close();` - -Works exactly like the [socket_close](http://php.net/manual/en/function.socket-close.php) function. - - -`public function getPeerName(bool $port = true);` - -Works like [socket_getpeername](http://php.net/manual/en/function.socket-getpeername.php): the difference is that it returns an array with the `host` and the `port`. - - -`public function getSockName(bool $port = true);` - -Works like [socket_getsockname](http://php.net/manual/en/function.socket-getsockname.php): the difference is that it returns an array with the `host` and the `port`. - - -`public function getProxyHeaders();` - -Can return additional HTTP headers to use when the HTTP protocol is being used. - -`public function getResource();` - -Returns the resource used for socket communication: should call `$socket->getResource()`. Next section \ No newline at end of file diff --git a/docs/docs/SETTINGS.md b/docs/docs/SETTINGS.md index 58e82ea8..6eb2c2b9 100644 --- a/docs/docs/SETTINGS.md +++ b/docs/docs/SETTINGS.md @@ -188,11 +188,11 @@ Description: Connection, read and write timeout for sockets ### `$settings['connection_settings']['all']['proxy']` Default: `\Socket` -Description: The [proxy class](PROXY.html) to use. +Description: The [proxy class (or array of proxy classes)](PROXY.html) to use: MTProxy, socks5 and HTTP proxies are supported by default. ### `$settings['connection_settings']['all']['proxy_extra']` Default: `[]` -Description: Extra parameters to pass to the proxy class using setExtra +Description: Extra parameters (or array of paremeters) to pass to the proxy class ### `$settings['connection_settings']['all']['pfs']` Default: `true` if `php-gmp` is installed, `false` otherwise @@ -336,6 +336,10 @@ Download settings Default: `1024*1024` Description: Default part size for file download +### `$settings['download']['report_broken_media']` +Default: `true` +Description: Whether or not to automatically report undownloadable media to support +
## `$settings['msg_array_limit']`