<commit_before>RFC 0162: HTTP Proxy
========================================================================
$Id$

@authors: friebe, kiesel, ohinckel
@created: Wed Apr 16 20:39:56     2008
@status: draft
@category: peer.http

Scope of Change
---------------
A functionality will be added to the peer.http.HttpConnection class to
support HTTP proxies.


Rationale
---------
Some machines in restricted networks may not access other networks
directly.


Functionality
-------------

API: The HttpProxy class
~~~~~~~~~~~~~~~~~~~~~~~~
<code>
  class HttpProxy extends Object {
    
    /**
     * Constructor
     *
     * @param   string host
     * @param   int port default 8080
     */
    public function __construct($host, $port= 8080) {
      // ...
    }

    /**
     * Add a URL pattern to exclude.
     *
     * @param   string pattern
     */
    public function addExclude($pattern) {
      // ...
    }
    
    /**
     * Add a URL pattern to exclude and return this proxy. For use with
     * chained method calls.
     *
     * @param   string pattern
     * @return  peer.http.HttpProxy this object
     */
    public function withExclude($pattern) {
      // ...
    }
  }
</code>

API: The HttpConnection class
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<code>
  class HttpConnection extends Object {
  
    // ...

    /**
     * Set proxy
     *
     * @param   peer.http.HttpProxy proxy
     */
    public function setProxy(HttpProxy $proxy) {
      // ...
    }

    // ...

  }
</code>


Example
~~~~~~~
<code>
  $conn= new HttpConnection($url);
  $conn->setProxy(create(new HttpProxy($host, $port))
    ->withExclude('localhost')
    ->withExclude('.example.com')
  );
  $response= $this->conn->get();
</code>


Security considerations
-----------------------
n/a

Speed impact
------------
n/a

Dependencies
------------
n/a

Related documents
-----------------
- http://www.innovation.ch/java/HTTPClient/advanced_info.html
  Advanced HTTPClient Info

- http://xp-framework.net/rfc/contrib/rfc0162.diff
  Implementing patch


Comments
--------

<EOF><commit_msg>- Set status to discussion - Whitespace - Add comment on implementation details<commit_after>RFC 0162: HTTP Proxy
========================================================================
$Id$

@authors: friebe, kiesel, ohinckel
@created: Wed Apr 16 20:39:56     2008
@status: discussion, ends Wed Jun  3 18:00:00     2008
@category: peer.http

Scope of Change
---------------
A functionality will be added to the peer.http.HttpConnection class to
support HTTP proxies.


Rationale
---------
Some machines in restricted networks may not access other networks
directly.


Functionality
-------------

API: The HttpProxy class
~~~~~~~~~~~~~~~~~~~~~~~~
<code>
  class HttpProxy extends Object {
    
    /**
     * Constructor
     *
     * @param   string host
     * @param   int port default 8080
     */
    public function __construct($host, $port= 8080) {
      // ...
    }
    
    /**
     * Add a URL pattern to exclude.
     *
     * @param   string pattern
     */
    public function addExclude($pattern) {
      // ...
    }
    
    /**
     * Add a URL pattern to exclude and return this proxy. For use with
     * chained method calls.
     *
     * @param   string pattern
     * @return  peer.http.HttpProxy this object
     */
    public function withExclude($pattern) {
      // ...
    }
  }
</code>

API: The HttpConnection class
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<code>
  class HttpConnection extends Object {
    // ...
    
    /**
     * Set proxy
     *
     * @param   peer.http.HttpProxy proxy
     */
    public function setProxy(HttpProxy $proxy) {
      // ...
    }
    
    // ...
  }
</code>


Example
~~~~~~~
<code>
  $conn= new HttpConnection($url);
  $conn->setProxy(create(new HttpProxy($host, $port))
    ->withExclude('localhost')
    ->withExclude('.example.com')
  );
  $response= $this->conn->get();
</code>


Security considerations
-----------------------
n/a

Speed impact
------------
n/a

Dependencies
------------
n/a

Related documents
-----------------
* Advanced HTTPClient Info:
  http://www.innovation.ch/java/HTTPClient/advanced_info.html
* Implementing patch
  http://xp-framework.net/rfc/contrib/rfc0162.diff


Comments
--------
friebe, Sun Jun  1 13:56:30     2008
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
I'm not really happy with the implementation, and it is not testable
in an easy fashion. Since the HttpConnection class itself isn't easily
testable either and accessing the request (e.g. for logging purposes)
is hacky, too (can't be done until is has been sent!), maybe we should
rewrite completely within this RFC (thus delaying it longer, though).

<EOF>
{'fraction_non_alphanumeric': 0.20755925688661114, 'fraction_numerical': 0.016655989750160152, 'mean_word_length': 2.2595685455810717, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 27, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '717060', 'n_tokens_mistral': 1436, 'n_tokens_neox': 1332, 'n_words': 400}