danog/MadelineProtoDocs
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Write new proxy docs

Browse Source
This commit is contained in:
Daniil Gentili 2019-06-01 14:03:34 +02:00
parent e8e22ca165
commit af0458d42d
3 changed files with 134 additions and 125 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
docs/docs/INSTALLATION.md
View File

@ -44,9 +44,6 @@ composer.json:
"type": "project", "type": "project",
"require": { "require": {
"danog/madelineproto": "dev-master", "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": [ "repositories": [
{ {
@ -104,10 +101,6 @@ Then you can require the package by addding the following lines to the require s
``` ```
"danog/madelineproto":"dev-master", "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"
``` ```
<a href="https://docs.madelineproto.xyz/docs/UPDATES.html">Next section</a> <a href="https://docs.madelineproto.xyz/docs/UPDATES.html">Next section</a>

242
docs/docs/PROXY.md
View File

@ -7,20 +7,115 @@ image: https://docs.madelineproto.xyz/favicons/android-chrome-256x256.png
You can use a proxy with MadelineProto. 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 Socks5 proxy](#socks5-proxy)
* [Use pre-built HTTP proxy](#http-proxy) * [Use pre-built HTTP proxy](#http-proxy)
* [Build your own proxy](#build-your-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 ## Socks5 proxy
No password: No password:
```php ```php
$settings['connection_settings']['all']['proxy'] = '\SocksProxy'; use danog\MadelineProto\Stream\Proxy\SocksProxy;
$settings['connection_settings']['all']['proxy_extra'] = ['address' => $proxy_address, 'port' => $proxy_port];
$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); $MadelineProto = new \danog\MadelineProto\API('session.madeline', $settings);
``` ```
@ -29,8 +124,15 @@ $MadelineProto = new \danog\MadelineProto\API('session.madeline', $settings);
With password: With password:
```php ```php
$settings['connection_settings']['all']['proxy'] = '\SocksProxy'; use danog\MadelineProto\Stream\Proxy\SocksProxy;
$settings['connection_settings']['all']['proxy_extra'] = ['address' => $proxy_address, 'port' => $proxy_port, 'username' => 'user', 'password' => 'afnjasf'];
$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); $MadelineProto = new \danog\MadelineProto\API('session.madeline', $settings);
``` ```
@ -40,8 +142,13 @@ $MadelineProto = new \danog\MadelineProto\API('session.madeline', $settings);
No password: No password:
```php ```php
$settings['connection_settings']['all']['proxy'] = '\HttpProxy'; use danog\MadelineProto\Stream\Proxy\HttpProxy;
$settings['connection_settings']['all']['proxy_extra'] = ['address' => $proxy_address, 'port' => $proxy_port];
$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); $MadelineProto = new \danog\MadelineProto\API('session.madeline', $settings);
``` ```
@ -50,8 +157,15 @@ $MadelineProto = new \danog\MadelineProto\API('session.madeline', $settings);
With password: With password:
```php ```php
$settings['connection_settings']['all']['proxy'] = '\HttpProxy'; use danog\MadelineProto\Stream\Proxy\HttpProxy;
$settings['connection_settings']['all']['proxy_extra'] = ['address' => $proxy_address, 'port' => $proxy_port, 'username' => 'user', 'password' => 'afnjasf'];
$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); $MadelineProto = new \danog\MadelineProto\API('session.madeline', $settings);
``` ```
@ -59,111 +173,9 @@ $MadelineProto = new \danog\MadelineProto\API('session.madeline', $settings);
## Build your proxy ## Build your proxy
```php In order to build your proxy, you have to use the new MadelineProto stream API to create your own proxy class.
class MyProxy implements \danog\MadelineProto\Proxy 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!
//...
}
$MadelineProto->settings['connection_settings']['all']['proxy'] = '\MyProxy';
```
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()`.
<a href="https://docs.madelineproto.xyz/docs/USING_METHODS.html">Next section</a> <a href="https://docs.madelineproto.xyz/docs/USING_METHODS.html">Next section</a>

8
docs/docs/SETTINGS.md
View File

@ -188,11 +188,11 @@ Description: Connection, read and write timeout for sockets
### `$settings['connection_settings']['all']['proxy']` ### `$settings['connection_settings']['all']['proxy']`
Default: `\Socket` 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']` ### `$settings['connection_settings']['all']['proxy_extra']`
Default: `[]` 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']` ### `$settings['connection_settings']['all']['pfs']`
Default: `true` if `php-gmp` is installed, `false` otherwise Default: `true` if `php-gmp` is installed, `false` otherwise
@ -336,6 +336,10 @@ Download settings
Default: `1024*1024` Default: `1024*1024`
Description: Default part size for file download 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
<hr> <hr>
## `$settings['msg_array_limit']` ## `$settings['msg_array_limit']`