Make HTTP handler constructor free of socket file number

README.md

@@ -3,9 +3,9 @@
 [![License](https://img.shields.io/github/license/abhinavsingh/proxy.py.svg)](https://opensource.org/licenses/BSD-3-Clause)
 [![Build Status](https://travis-ci.org/abhinavsingh/proxy.py.svg?branch=develop)](https://travis-ci.org/abhinavsingh/proxy.py/)
 [![No Dependencies](https://img.shields.io/static/v1?label=dependencies&message=none&color=green)](https://github.com/abhinavsingh/proxy.py)
-[![Coverage](https://codecov.io/gh/abhinavsingh/proxy.py/branch/develop/graph/badge.svg)](https://codecov.io/gh/abhinavsingh/proxy.py)
 [![PyPi Monthly](https://img.shields.io/pypi/dm/proxy.py.svg?color=green)](https://pypi.org/project/proxy.py/)
 [![Docker Pulls](https://img.shields.io/docker/pulls/abhinavsingh/proxy.py?color=green)](https://hub.docker.com/r/abhinavsingh/proxy.py)
+[![Coverage](https://codecov.io/gh/abhinavsingh/proxy.py/branch/develop/graph/badge.svg)](https://codecov.io/gh/abhinavsingh/proxy.py)
 
 [![Tested With MacOS, Ubuntu, Windows, Android, Android Emulator, iOS, iOS Simulator](https://img.shields.io/static/v1?label=tested%20with&message=mac%20OS%20%F0%9F%92%BB%20%7C%20Ubuntu%20%F0%9F%96%A5%20%7C%20Windows%20%F0%9F%92%BB&color=brightgreen)](https://abhinavsingh.com/proxy-py-a-lightweight-single-file-http-proxy-server-in-python/)
 [![Android, Android Emulator](https://img.shields.io/static/v1?label=tested%20with&message=Android%20%F0%9F%93%B1%20%7C%20Android%20Emulator%20%F0%9F%93%B1&color=brightgreen)](https://abhinavsingh.com/proxy-py-a-lightweight-single-file-http-proxy-server-in-python/)
@@ -58,6 +58,9 @@ Table of Contents
     * [Plugin Ordering](#plugin-ordering)
 * [End-to-End Encryption](#end-to-end-encryption)
 * [TLS Interception](#tls-interception)
+* [Proxy Over SSH Tunnel](#proxy-over-ssh-tunnel)
+    * [Proxy Remote Requests Locally](#proxy-remote-requests-locally)
+    * [Proxy Local Requests Remotely](#proxy-local-requests-remotely)
 * [Embed proxy.py](#embed-proxypy)
     * [Blocking Mode](#blocking-mode)
     * [Non-blocking Mode](#non-blocking-mode)
@@ -798,6 +801,92 @@ cached file instead of plain text.
 Now use CA flags with other 
 [plugin examples](#plugin-examples) to see them work with `https` traffic.
 
+Proxy Over SSH Tunnel
+=====================
+
+Requires `paramiko` to work. See [requirements-tunnel.txt](https://github.com/abhinavsingh/proxy.py/blob/develop/requirements-tunnel.txt)
+
+## Proxy Remote Requests Locally
+
+                            |
+    +------------+          |            +----------+
+    |   LOCAL    |          |            |  REMOTE  |
+    |   HOST     | <== SSH ==== :8900 == |  SERVER  |
+    +------------+          |            +----------+
+    :8899 proxy.py          |
+                            |
+                         FIREWALL
+                      (allow tcp/22)
+
+## What
+
+Proxy HTTP(s) requests made on a `remote` server through `proxy.py` server
+running on `localhost`.
+
+### How
+
+* Requested `remote` port is forwarded over the SSH connection.
+* `proxy.py` running on the `localhost` handles and responds to
+  `remote` proxy requests.
+
+### Requirements
+
+1. `localhost` MUST have SSH access to the `remote` server
+2. `remote` server MUST be configured to proxy HTTP(s) requests
+   through the forwarded port number e.g. `:8900`.
+   - `remote` and `localhost` ports CAN be same e.g. `:8899`.
+   - `:8900` is chosen in ascii art for differentiation purposes.
+
+### Try it
+
+Start `proxy.py` as:
+
+```
+$ # On localhost
+$ proxy --enable-tunnel \
+    --tunnel-username username \
+    --tunnel-hostname ip.address.or.domain.name \
+    --tunnel-port 22 \
+    --tunnel-remote-host 127.0.0.1
+    --tunnel-remote-port 8899
+```
+
+Make a HTTP proxy request on `remote` server and 
+verify that response contains public IP address of `localhost` as origin:
+
+```
+$ # On remote
+$ curl -x 127.0.0.1:8899 http://httpbin.org/get
+{
+  "args": {},
+  "headers": {
+    "Accept": "*/*",
+    "Host": "httpbin.org",
+    "User-Agent": "curl/7.54.0"
+  },
+  "origin": "x.x.x.x, y.y.y.y",
+  "url": "https://httpbin.org/get"
+}
+```
+
+Also, verify that `proxy.py` logs on `localhost` contains `remote` IP as client IP.
+
+```
+access_log:328 - remote:52067 - GET httpbin.org:80
+```
+
+## Proxy Local Requests Remotely
+
+                            |
+    +------------+          |     +----------+
+    |   LOCAL    |          |     |  REMOTE  |
+    |   HOST     | === SSH =====> |  SERVER  |
+    +------------+          |     +----------+
+                            |     :8899 proxy.py
+                            |
+                        FIREWALL
+                     (allow tcp/22)
+
 Embed proxy.py
 ==============
 

proxy/core/acceptor/__init__.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+"""
+    proxy.py
+    ~~~~~~~~
+    ⚡⚡⚡ Fast, Lightweight, Pluggable, TLS interception capable proxy server focused on
+    Network monitoring, controls & Application development, testing, debugging.
+
+    :copyright: (c) 2013-present by Abhinav Singh and contributors.
+    :license: BSD, see LICENSE for more details.
+"""
+from .acceptor import Acceptor
+from .pool import AcceptorPool
+
+__all__ = [
+    'Acceptor',
+    'AcceptorPool',
+]

proxy/core/acceptor/acceptor.py

@@ -0,0 +1,137 @@
+# -*- coding: utf-8 -*-
+"""
+    proxy.py
+    ~~~~~~~~
+    ⚡⚡⚡ Fast, Lightweight, Pluggable, TLS interception capable proxy server focused on
+    Network monitoring, controls & Application development, testing, debugging.
+
+    :copyright: (c) 2013-present by Abhinav Singh and contributors.
+    :license: BSD, see LICENSE for more details.
+"""
+import logging
+import multiprocessing
+import selectors
+import socket
+import threading
+# import time
+from multiprocessing import connection
+from multiprocessing.reduction import send_handle, recv_handle
+from typing import Optional, Type, Tuple
+
+from ..connection import TcpClientConnection
+from ..threadless import ThreadlessWork, Threadless
+from ..event import EventQueue, eventNames
+from ...common.flags import Flags
+
+logger = logging.getLogger(__name__)
+
+
+class Acceptor(multiprocessing.Process):
+    """Socket client acceptor.
+
+    Accepts client connection over received server socket handle and
+    starts a new work thread.
+    """
+
+    lock = multiprocessing.Lock()
+
+    def __init__(
+            self,
+            idd: int,
+            work_queue: connection.Connection,
+            flags: Flags,
+            work_klass: Type[ThreadlessWork],
+            event_queue: Optional[EventQueue] = None) -> None:
+        super().__init__()
+        self.idd = idd
+        self.work_queue: connection.Connection = work_queue
+        self.flags = flags
+        self.work_klass = work_klass
+        self.event_queue = event_queue
+
+        self.running = multiprocessing.Event()
+        self.selector: Optional[selectors.DefaultSelector] = None
+        self.sock: Optional[socket.socket] = None
+        self.threadless_process: Optional[Threadless] = None
+        self.threadless_client_queue: Optional[connection.Connection] = None
+
+    def start_threadless_process(self) -> None:
+        pipe = multiprocessing.Pipe()
+        self.threadless_client_queue = pipe[0]
+        self.threadless_process = Threadless(
+            client_queue=pipe[1],
+            flags=self.flags,
+            work_klass=self.work_klass,
+            event_queue=self.event_queue
+        )
+        self.threadless_process.start()
+        logger.debug('Started process %d', self.threadless_process.pid)
+
+    def shutdown_threadless_process(self) -> None:
+        assert self.threadless_process and self.threadless_client_queue
+        logger.debug('Stopped process %d', self.threadless_process.pid)
+        self.threadless_process.running.set()
+        self.threadless_process.join()
+        self.threadless_client_queue.close()
+
+    def start_work(self, conn: socket.socket, addr: Tuple[str, int]) -> None:
+        if self.flags.threadless and \
+                self.threadless_client_queue and \
+                self.threadless_process:
+            self.threadless_client_queue.send(addr)
+            send_handle(
+                self.threadless_client_queue,
+                conn.fileno(),
+                self.threadless_process.pid
+            )
+            conn.close()
+        else:
+            work = self.work_klass(
+                TcpClientConnection(conn, addr),
+                flags=self.flags,
+                event_queue=self.event_queue
+            )
+            work_thread = threading.Thread(target=work.run)
+            work_thread.daemon = True
+            work.publish_event(
+                event_name=eventNames.WORK_STARTED,
+                event_payload={'fileno': conn.fileno(), 'addr': addr},
+                publisher_id=self.__class__.__name__
+            )
+            work_thread.start()
+
+    def run_once(self) -> None:
+        assert self.selector and self.sock
+        with self.lock:
+            events = self.selector.select(timeout=1)
+            if len(events) == 0:
+                return
+            conn, addr = self.sock.accept()
+        # now = time.time()
+        # fileno: int = conn.fileno()
+        self.start_work(conn, addr)
+        # logger.info('Work started for fd %d in %f seconds', fileno, time.time() - now)
+
+    def run(self) -> None:
+        self.selector = selectors.DefaultSelector()
+        fileno = recv_handle(self.work_queue)
+        self.work_queue.close()
+        self.sock = socket.fromfd(
+            fileno,
+            family=self.flags.family,
+            type=socket.SOCK_STREAM
+        )
+        try:
+            self.selector.register(self.sock, selectors.EVENT_READ)
+            if self.flags.threadless:
+                self.start_threadless_process()
+            while not self.running.is_set():
+                self.run_once()
+        except KeyboardInterrupt:
+            pass
+        finally:
+            self.selector.unregister(self.sock)
+            if self.flags.threadless:
+                self.shutdown_threadless_process()
+            self.sock.close()
+            logger.debug('Acceptor#%d shutdown', self.idd)