skeleton commit; based on an anom project

1 files changed, 169 insertions, 0 deletions

diff --git a/core/classes/session/SessionHandlerInterface.php b/core/classes/session/SessionHandlerInterface.php
new file mode 100644
index 0000000..cf6efac
--- /dev/null
+++ b/core/classes/session/SessionHandlerInterface.php
@@ -0,0 +1,169 @@
+<?php
+
+/** SessionHandlerInterface
+ * 
+ * as of php's documentation (check manual)
+ * https://www.php.net/manual/en/class.sessionhandlerinterface.php
+ */
+interface SessionHandlerInterface
+{
+
+    /* Methods
+     *--------------------------------------------------------------------------
+     */
+
+    public function open(string $path, string $name) : bool;
+
+    public function close() : bool;
+
+    public function read(string $id) : string|false;
+
+    public function write(string $id, string $data) : bool;
+
+    public function destroy(string $id) : bool;
+    
+    public function gc(int $max_lifetime) : int|false;
+    
+}
+
+/** TODO: (thoughts)
+ * ... for a brand-new session implementation
+ * 
+ * In most cases, the session data does not require persistence.
+ * The session information could be cached to improve performance
+ * 
+ * So (in theory) we could create a two-dimension session mechanism
+ * 
+ * + a fast dimension
+ * : could be file-based (using local FS [php's default?] or redis/memcached)
+ * 
+ * + a shared dimension
+ * : implemented in a shared database
+ * 
+ * Posible algo:
+ * ... (check later on this comment-block: session life-cycle )
+ * 
+ * open  : 
+ * close : on both
+ * read  : check Local; if not exist check database; set session_id($id)
+ * write : on both
+ * destroy : on both
+ * gc    : on server
+ * 
+ * when regenerating session_id, keep database informed about the new session_id
+ * when closing, keep database informed about the session end-of-life.
+ * 
+ * a session timeout on the local leg will trigger a confirm-session-from-db
+ * 
+ * garbage collector on the db should remove expired sessions of some X seconds
+ * and earier (X needs to be determined by practice/expirience/tries)
+ * 
+ * (+) in order to keep tracking of the session between multiple servers through
+ * the (shared) database, a unique secret-between-the-servers id can be used
+ * 
+ * so...
+ * 
+ * #1
+ * -> someone visits website through server A
+ * -> server A creates a new session-id for the visitor and a shared-session-id
+ * -> saves both into database
+ * 
+ * later...
+ * 
+ * #2
+ * -> the same device is connected (via loadbalancer) into server B
+ * -> server B don't have the session-id (send by the client) but gets it from db
+ *   (is session-id do not exist on the db, then this is a new session)
+ * 
+ * = now both server A and B have the same session-id localy
+ * 
+ * later...
+ * 
+ * #3
+ * -> some server (let's say B) regenerates the visitors session-id
+ * -> if later the visitor falls into server A, the A will retrieve the new
+ *   session id through the #2 scenario
+ * 
+ * this way 
+ * + any server can update/regenerate the visitor's session-id
+ * + the visitor can be served from both servers randomly
+ * + all session variables exist on the database (always)
+ * + all session variables exist on all servers synced-on-demand
+ * 
+ * 
+ * stucture of session:
+ * ---
+ * - shared-session-id: (secret + persistent); exposed between servers **primary
+ * - session-id: (may change/regenerate/update); exposed to the client **indexed
+ * - data: serialized array
+ * - creation_timestamp:
+ * - last_touched_timestamp:
+ * - expiration_timestamp: should point to the future or session has expired
+ * - csrf_token:
+ * - JWT_token
+ * - AES-key (this way private data can be kept in browser)
+ * 
+ * 
+ * what will kept on browser/client (via cookie)
+ * ---
+ * - session-name => session-id
+ * - user info => AES_ectypted(serialized[t=>csfr_token, u=> user_id, s=>SIGNATURE])
+ *
+ * 
+ * Writable file-system shall change
+ * (local writable file-system tree)
+ * ---
+ * /html/storage
+ *          |
+ *          |-- cache   : query-caches
+ *          |
+ *          `-- session : FS\sessions
+ *               |
+ *                `-- indexes : share-session-id indexes
+ * 
+ * 
+ * 
+ * NOTE: Session life-cycle
+ * 
+ * session_start() * firsts time
+ * ---
+ * ::open(path,PHPSESSID) -> (session_id not exist) -> false
+ * ::create_sid -> '123def'
+ * ::read('123def') ?-or/and- ::close()
+ * 
+ * 
+ * session_start() * next times
+ * ---
+ * ::open(path, PHPSESSID) -> (session_id exist) -> true
+ * ::read('123def') -> return data -> will fill $_SESSION[*]
+ * 
+ * 
+ * $_SESSION['foo'] = 'bar';
+ * ---
+ * ::write('123def', 'foo|s:3:"bar";') -> ['foo' => "bar"]
+ * ::close()
+ * 
+ * 
+ * session_regenerate_id();
+ * ---
+ * ::create_sid() -> def123
+ * 
+ * 
+ * session_reset()
+ * ---
+ * ::open()
+ * ::read('def123')
+ * 
+ * 
+ * session_write_close()
+ * ---
+ * ::write('123def', 'foo|s:3:"bar";')
+ * ::close()
+ * 
+ * 
+ * session_destroy()
+ * ---
+ * ::destroy('def123')
+ * ::close()
+ *
+ */