Add the ability to change the hostname&service from a TCPConnectionNotify before connecting (#3230)

Added proxy_via to the tcp_connection_notify with a default implementation; used it in the tcp_connection constructors.

Allows for proxies to be implemented by decorating a TCPConnectionNotify with another.

Author: CandleCandle

CHANGELOG.md

@@ -12,6 +12,7 @@ All notable changes to the Pony compiler and standard library will be documented
 
 - Add `--link-ldcmd` command line argument for overriding the `ld` command used for linking ([PR #3259](https://github.com/ponylang/ponyc/pull/3259))
 - Make builds with `musl` on `glibc` systems possible ([PR #3263](https://github.com/ponylang/ponyc/pull/3263))
+- Add `proxy_via(destination_host, destination_service)` to `TCPConnectionNotify` to allow TCP handlers to change the hostname & service from a TCPConnectionNotify before connecting ([PR #3230](https://github.com/ponylang/ponyc/pull/3230))
 
 ### Changed
 

packages/net/_test.pony

@@ -17,6 +17,7 @@ actor Main is TestList
     ifdef not windows then
       test(_TestTCPThrottle)
     end
+    test(_TestTCPProxy)
 
 class _TestPing is UDPNotify
   let _h: TestHelper
@@ -639,3 +640,32 @@ class _TestTCPThrottleSendNotify is TCPConnectionNotify
       conn.write("this is more data that you won't ever read" * 10000)
     end
     data
+
+class _TestTCPProxy is UnitTest
+  """
+  Check that the proxy callback is called on creation of a TCPConnection.
+  """
+  fun name(): String => "net/TCPProxy"
+  fun exclusion_group(): String => "network"
+
+  fun ref apply(h: TestHelper) =>
+    h.expect_action("sender connected") 
+    h.expect_action("sender proxy request") 
+
+    _TestTCP(h)(_TestTCPProxyNotify(h),
+      _TestTCPProxyNotify(h))
+
+class _TestTCPProxyNotify is TCPConnectionNotify
+  let _h: TestHelper
+  new iso create(h: TestHelper) =>
+    _h = h
+
+  fun ref proxy_via(host: String, service: String): (String, String) =>
+    _h.complete_action("sender proxy request")
+    (host, service)
+    
+  fun ref connected(conn: TCPConnection ref) =>
+    _h.complete_action("sender connected")
+
+  fun ref connect_failed(conn: TCPConnection ref) =>
+    _h.fail_action("sender connect failed")

packages/net/proxy.pony

@@ -0,0 +1,19 @@
+
+interface Proxy
+  fun apply(wrap: TCPConnectionNotify iso): TCPConnectionNotify iso^
+
+class val NoProxy is Proxy
+  """
+  Default implementation of a proxy that does not alter the supplied `TCPConnectionNotify`.
+
+  ```pony
+  actor MyClient
+    new create(host: String, service: String, proxy: Proxy = NoProxy) =>
+      let conn: TCPConnection = TCPConnection.create(
+        env.root as AmbientAuth,
+        proxy.apply(MyConnectionNotify.create()),
+        "localhost",
+        "80")
+  ```
+  """
+  fun apply(wrap: TCPConnectionNotify iso): TCPConnectionNotify iso^ => wrap

packages/net/tcp_connection.pony

@@ -190,6 +190,80 @@ actor TCPConnection
   these platforms, you **must** call `unmute` on a muted connection to have
   it close. Without calling `unmute` the `TCPConnection` actor will never
   exit.
+
+  ## Proxy support
+
+  Using the `proxy_via` callback in a `TCPConnectionNotify` it is possible
+  to implement proxies. The function takes the intended destination host
+  and service as parameters and returns a 2-tuple of the proxy host and
+  service.
+
+  The proxy `TCPConnectionNotify` should decorate another implementation of
+  `TCPConnectionNotify` passing relevent data through.
+
+  ### Example proxy implementation
+
+  ```pony
+  actor Main
+    new create(env: Env) =>
+      MyClient.create(
+        "example.com", // we actually want to connect to this host
+        "80",
+        ExampleProxy.create("proxy.example.com", "80")) // we connect via this proxy
+
+  actor MyClient
+    new create(host: String, service: String, proxy: Proxy = NoProxy) =>
+      let conn: TCPConnection = TCPConnection.create(
+        env.root as AmbientAuth,
+        proxy.apply(MyConnectionNotify.create()),
+        host,
+        service)
+
+  class ExampleProxy is Proxy
+    let _proxy_host: String
+    let _proxy_service: String
+
+    new create(proxy_host: String, proxy_service: String) =>
+      _proxy_host = proxy_host
+      _proxy_service = proxy_service
+
+    fun apply(wrap: TCPConnectionNotify iso): TCPConnectionNotify iso^ =>
+      ExampleProxyNotify.create(consume wrap, _proxy_service, _proxy_service)
+
+  class iso ExampleProxyNotify is TCPConnectionNotify
+    // Fictional proxy implementation that has no error
+    // conditions, and always forwards the connection.
+    let _proxy_host: String
+    let _proxy_service: String
+    var _destination_host: (None | String) = None
+    var _destination_service: (None | String) = None
+    let _wrapped: TCPConnectionNotify iso
+
+    new iso create(wrap: TCPConnectionNotify iso, proxy_host: String, proxy_service: String) =>
+      _wrapped = wrap
+      _proxy_host = proxy_host
+      _proxy_service = proxy_service
+
+    fun ref proxy_via(host: String, service: String): (String, String) =>
+      // Stash the original host & service; return the host & service
+      // for the proxy; indicating that the initial TCP connection should
+      // be made to the proxy
+      _destination_host = host
+      _destination_service = service
+      (_proxy_host, _proxy_service)
+
+    fun ref connected(conn: TCPConnection ref) =>
+      // conn is the connection to the *proxy* server. We need to ask the
+      // proxy server to forward this connection to our intended final
+      // destination.
+      conn.write((_destination_host + "\n").array())
+      conn.write((_destination_service + "\n").array())
+      wrapped.connected(conn)
+
+    fun ref received(conn, data, times) => _wrapped.received(conn, data, times)
+    fun ref connect_failed(conn: TCPConnection ref) => None
+  ```
+  
   """
   var _listen: (TCPListener | None) = None
   var _notify: TCPConnectionNotify
@@ -248,8 +322,9 @@ actor TCPConnection
       else
         AsioEvent.read_write()
       end
+    (let host', let service') = _notify.proxy_via(host, service)
     _connect_count =
-      @pony_os_connect_tcp[U32](this, host.cstring(), service.cstring(),
+      @pony_os_connect_tcp[U32](this, host'.cstring(), service'.cstring(),
         from.cstring(), asio_flags)
     _notify_connecting()
 
@@ -277,8 +352,9 @@ actor TCPConnection
       else
         AsioEvent.read_write()
       end
+    (let host', let service') = _notify.proxy_via(host, service)
     _connect_count =
-      @pony_os_connect_tcp4[U32](this, host.cstring(), service.cstring(),
+      @pony_os_connect_tcp4[U32](this, host'.cstring(), service'.cstring(),
         from.cstring(), asio_flags)
     _notify_connecting()
 
@@ -306,8 +382,9 @@ actor TCPConnection
       else
         AsioEvent.read_write()
       end
+    (let host', let service') = _notify.proxy_via(host, service)
     _connect_count =
-      @pony_os_connect_tcp6[U32](this, host.cstring(), service.cstring(),
+      @pony_os_connect_tcp6[U32](this, host'.cstring(), service'.cstring(),
         from.cstring(), asio_flags)
     _notify_connecting()
 

packages/net/tcp_connection_notify.pony

@@ -11,6 +11,27 @@ interface TCPConnectionNotify
     """
     None
 
+  fun ref proxy_via(host: String, service: String): (String, String) =>
+    """
+    Called before before attempting to connect to the destination server
+    In order to connect via proxy, return the host & service for the proxy
+    server.
+
+    An implementation of this function might look like:
+    ```pony
+    let _proxy_host = "some-proxy.example.com"
+    let _proxy_service = "80"
+    var _destination_host: ( None | String )
+    var _destination_service: ( None | String )
+
+    fun ref proxy_via(host: String, service: String): (String, String) =>
+      _destination_host = host
+      _destination_service = service
+      ( _proxy_host, _proxy_service )
+    ```
+    """
+    (host, service)
+
   fun ref connecting(conn: TCPConnection ref, count: U32) =>
     """
     Called if name resolution succeeded for a TCPConnection and we are now