Esprit Design
From Apis Networks Wiki
Contents |
About
apnscp esprit is the name for Apis Networks' upcoming control panel. To disambiguate from the old control panel, apnscp, it is commonly referred to as "esprit". Matt Saladna is the primary developer behind esprit with a few others occassionally sharing their insight.
Definitions
These should help you understand the confusing lingo used when discussing esprit:
- Couple
- To couple means to rely on another. Something tighly coupled has a strong dependence; loosely coupled means there is little dependence upon one another. Changing the function in function1 does not adversely affect function2. Loosely coupled is the preferred way of handling design.
- Function
- Any set of code contained within a callable PHP function
- Invoke
- Calling a function is said to be invoking a function, analogous to call
- Module
- A module is a PHP5 class consisting of similar functions. For example, there is a Web_Module class
- Operation
- Any function callable from SOAP
- Postback
- A form action on the Dashboard
- SOAP
- Originally meant Simple Object Access Protocol, now meaningless, it is used to transfer data over a TCP/IP connection, most commonly HTTP. SOAP uses XML to handle
data where it can then be transformed by any programming language into its corresponding constructs.
- Static
- Something that doesn't change through function invocations
Components
apnscp esprit uses two separate layers for handling communication with users. A frontend, called the Dashboard and backend called the Listener Service or in its abbreviated form, lService. lService is responsible for carrying out requests that require elevated privileges, e.g. updating a user's filesystem, removing a subdomain, creating a symbolic link, removing a file from the file manager, sudo'ing to a new user, et cetera.
The Dashboard handles everything else that can be done without elevated privileges. It is responsible for displaying the control panel links, making changes to a SQL table, setting up session information, or even accepting a form action (called a postback) and passing it off to the lService for further parsing.
To make everything a little more confusing, the Dashboard is further split up into a normal and SOAP version. The SOAP version, accessed via https://beta.cp.'''servername'''.apisnetworks.com/soap.php loads an abridged module set from the Dashboard and in turn uses its own special session handler for SOAP-based requests.
Question to be answered: How is the dashboard version accessed? If a person has an account at apisnetworks, how do they access their Control Panel?
Caching
Every Dashboard request is designed to load the modules it requires for that page instance. As it is built around PHP5, it suffers from PHP's teardown, build-up process of handling pages. That is to say in other words, every page request is a sandbox. Once the page's lifetime is over, that is to say once it is done loading, everything loaded into memory is removed. We attempt to offset this problem by caching static return values. If a return value from an operation is determined to be static (non-changing), then that value is stored in a MySQL table for later retrieval if the operation is invoked once again during a user's session.
lService caches a bit differently. Since it only executes operations and maintains those functions loaded in memory throughout the life of the lService instance, it loads every operation up in memory upon startup. From there it can quickly handle an elevated request. Once the lService is shutdown, memory allocated to the stored functions are released, just as with any other program.
Design Ideologies
As apnscp esprit took several months on the drawing board before it manifested itself into a control panel, it underwent many revisions and beliefs of how it should operate. Below is a listing of criteria that we adhere to when writing components to apnscp esprit:
- Ensure the function interceptor has a single instance across the lService or Dashboard enforced via a Singleton pattern
- Cache any static return value, if the time spent on (caching + gziping + storing) + (decompressing + retrieving)/avg frequency is greater than the time spent executing and displaying, ignore the cache
- Reuse as little of apnscp's codebase as possible. This is a horribly written control panel. Rewrite everything from scratch
- Avoid any built-in Ensim functions. For any Ensim-related function, mark a @TODO in the documentation to rework it in the future, esprit eventually should be decoupled from Ensim entirely
- Write as little code as possible to accomplish the task. Reusing existing functions in esprit's codebase is acceptable and preferred.
- Keep modules as lightweight as possible, splitting up if necessary. Each Dashboard request loads the operation's class (module), therefore a 125 KB class file of dissimilar operations would cause a severe performance hit
- Avoid throwing an error, instead return a new instance
- We're still not sure on how to handle errors. Throwing an error returns the stack. All errors right now are derived from the base Exception class, which causes a stack trace. On a 900 MHz P3 box, this translates to roughly 2 exceptions every second that can be passed from the SOAP server to the SOAP client.
- Avoid tightly coupling any two functions. If you want to reuse a function, that's fine, but make sure the base data sent to the function is picked up and transformed prior to sending to the helper function. This avoids breaking dependencies with future changes to esprit.
