| .. Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| |
| .. include:: ../common.defs |
| |
| .. _client-session-architecture: |
| |
| An Overview Client Sessions and Transactions |
| ******************************************** |
| |
| |
| The User Agent interacts with ATS by creating a session with the ATS server and |
| submitting sequences of requests over the session. ATS supports several session protocols including |
| HTTP/1.x and HTTP/2. A HTTP State Machine is created for each request to process the request. |
| |
| ATS uses the generic classes ProxySession and ProxyTransaction to hide the details of |
| the underlying protocols from the HTTP State Machine. |
| |
| Classes |
| ======= |
| |
| ProxySession |
| ------------------ |
| |
| .. figure:: /static/images/sessions/session_hierarchy.png |
| :align: center |
| :alt: ProxySession hierarchy |
| |
| The ProxySession class abstracts the key features of a client session. It contains zero or more ProxyTransaction objects. It also has a reference to the associated NetVC (either UnixNetVConnection or SSLNetVConnection). The session class is responsible for interfacing with the user agent protocol. |
| |
| At this point there are two concrete subclasses: Http1ClientSession and Http2ClientSession. The Http1ClientSession |
| only has at most one transaction active at a time. The HTTP/2 protocol allows for multiple simultaneous active |
| transactions |
| |
| ProxyTransaction |
| ---------------------- |
| |
| .. figure:: /static/images/sessions/transaction_hierarchy.png |
| :align: center |
| :alt: ProxyTransaction hierarchy |
| |
| The ProxyTransaction class abstracts the key features of a client transaction. It has a reference to its |
| parent ProxySession. One HttpSM is created for each ProxyTransaction. |
| |
| There are two concrete subclasses: Http1Transaction and Http2Stream. |
| |
| Session Object Relationships |
| ============================ |
| |
| HTTP/1.x Objects |
| ---------------- |
| |
| .. figure:: /static/images/sessions/http1_session_objects.png |
| :align: center |
| :alt: HTTP1 session objects |
| |
| This diagram shows the relationships between objects created as part of a HTTP/1.x session. A NetVC |
| object performs the basic network level protocols. The Http1ClientSession object has a reference to the |
| associated NetVC object. The NetVC object is available via the :code:`ProxySession::get_netvc()` method. |
| |
| The Http1ClientSession object contains a Http1Transaction object. For each HTTP request, it calls |
| the :code:`ProxySession::new_transaction()` method to instantiate the Http1Transaction object. With the HTTP/1.x |
| protocol at most one transaction can be active at a time. |
| |
| When the Http1Transaction object is instantiated via :code:`ProxyTransaction::new_transaction()` it allocates a |
| new HttpSM object, initializes it, and calls :code:`HttpSM::attach_client_session()` to associate the |
| Http1Transaction object with the new HttpSM. |
| |
| The ProxyTransaction object refers to the HttpSM via the _sm member variable. The HttpSM object |
| refers to ProxyTransaction via the ua_session member variable (session in the member name is |
| historical because the HttpSM used to refer directly to the ClientSession object). |
| |
| HTTP/2 Objects |
| -------------- |
| |
| .. figure:: /static/images/sessions/http2_session_objects.png |
| :align: center |
| :alt: HTTP/2 session objects |
| |
| This diagram shows the relationships between objects created as part of a HTTP/2 session. It is very similar |
| to the HTTP/1.x case. The Http2ClientSession object interacts with the NetVC. The Http2Stream object creates |
| a HttpSM object when :code:`ProxyClient::new_transaction()` is called. |
| |
| One difference is that the Http/2 protocol allows for multiple simultaneous transactions, so the Http2ClientSession |
| object must be able to manage multiple streams. From the HttpSM perspective it is interacting with a |
| ProxyTransaction object, and there is no difference between working with a Http2Stream and a Http1Transaction. |
| |
| Transaction and Session Shutdown |
| ================================ |
| |
| One of the trickiest bits of managing sessions and transactions is cleaning things up accurately and in a timely fashion. |
| In addition, the TXN_CLOSE hooks and SSN_CLOSE hooks must be executed accurately. The TXN_CLOSE hooks must be |
| executed exactly once. The SSN_CLOSE hook must also be executed exactly once and only after all the TXN_CLOSE |
| hooks of all the child transactions have been executed. The CLOSE hooks are important for many plugins to ensure that |
| plugin allocated objects are appropriately reclaimed. |
| |
| If objects are not cleaned up, memory leaks will occurs. If objects are reclaimed too soon, delayed events may |
| cause use-after-free and other related memory corruption errors. |
| |
| To ensure that sessions and transactions are correctly shutdown the following assertions are maintained. |
| |
| * The Session object will not call :code:`::destroy()` on itself until all child transaction objects are fully shutdown (i.e. TXN_CLOSE hooks are called and the transaction objects have been freed). |
| * The Transaction object will not call :code:`::destroy()` on itself until the associated HttpSM has been shutdown. In :code:`HttpSM::kill_this()`, the HttpSM will call :code:`ProxyTransaction::transaction_done()` on the ua_session object. If the user agent initiates the termination, the ProxyTransaction object will send a WRITE_COMPLETE, EOS, or ERROR event on the open VIO object. This should signal to the HttpSM object to shut itself down. |
| |