final report draft 1 for iskm

1 files changed, 175 insertions, 97 deletions

diff --git a/IBRAHIM_MKUSA.md b/IBRAHIM_MKUSA.md
index a24560c..48a7ed1 100644
--- a/IBRAHIM_MKUSA.md
+++ b/IBRAHIM_MKUSA.md
@@ -1,36 +1,39 @@
-# Interface to Google Drive in Racket
+# Hermes - A chat server and client written in Racket
 
-## Fred Martin
-### April 22, 2017
+## Ibrahim Mkusa
+### April 30, 2017
 
 # Overview
-This set of code provides an interface to searching through one's Google Drive account. 
-Its most important feature is that it provides a *folder-delimited search*.
+Hermes is a chat server and client written in Racket. One can run the Hermes
+server on any machine that is internet accessible. The Hermes clients then
+connect to the server from anywhere on the internet. It's inspired by chat
+systems and clients like irc.
 
-The essential model of files in Google Drive is that they are in one big “pile.” So you can't directly find a file in a
-given folder.
+The goal in building Hermes was to expose myself to several concepts integral to
+systems like networking, synchronization, and multitasking.
 
-This code recursively collects all folders found within a given folder, and then 
-construct a search query that includes a list of all the subfolders (flattened into a single list).
-
-This then allows you to perform a folder-delimited search.
 
 **Authorship note:** All of the code described here was written by myself.
 
 # Libraries Used
-The code uses four libraries:
+Most libraries and utilities used are part of base Drracket installation and
+therefore do not need to be imported.
+
+The date and time modules were used for various time related queries.
+The tcp module was used for communication via Transmission Control Protocol.
+Concurrency and synchronization modules that provide threads, and semaphores
+were also used.
+
+Below are libraries that were not part of base system:
 
 ```
-(require net/url)
-(require (planet ryanc/webapi:1:=1/oauth2))
-(require json)
-(require net/uri-codec)
+(require racket/gui/base)
+(require math/base)
 ```
 
-* The ```net/url``` library provides the ability to make REST-style https queries to the Google Drive API.
-* Ryan Culpepper's ```webapi``` library is used to provide the ```oauth2``` interface required for authentication.
-* The ```json``` library is used to parse the replies from the Google Drive API.
-* The ```net/uri-codec``` library is used to format parameters provided in API calls into an ASCII encoding used by Google Drive.
+* The ```racket/gui/base``` library used to build graphical user interface.
+* The ```math/base``` library was used for testing purposes. It was used to
+generated random numbers.
 
 # Key Code Excerpts
 
@@ -39,116 +42,187 @@ UMass Lowell's COMP.3010 Organization of Programming languages course.
 
 Five examples are shown and they are individually numbered. 
 
-## 1. Initialization using a Global Object
+## 1. Tracking client connections using an object and closures.
 
-The following code creates a global object, ```drive-client``` that is used in each of the subsequent API calls:
+The following code defines and creates a global object, ```make-connections```
+that abstracts client connections. It also creates a semaphore to control access
+to ```make-connections``` object.
 
 ```
-(define drive-client
-  (oauth2-client
-   #:id "548798434144-6s8abp8aiqh99bthfptv1cc4qotlllj6.apps.googleusercontent.com"
-   #:secret "<email me for secret if you want to use my API>"))
+(define (make-connections connections)
+  (define (null-cons?)
+    (null? connections))
+   (define (add username in out)
+    (set! connections (append connections (list (list username in out))))
+    connections)
+   (define (cons-list)
+     connections)
+   (define (remove-ports in out)
+     (set! connections
+       (filter 
+         (lambda (ports)
+           (if (and (eq? in (get-input-port ports))
+                    (eq? out (get-output-port ports)))
+             #f
+             #t))
+         connections)))
+   (define (dispatch m)
+     (cond [(eq? m 'null-cons) null-cons?]
+           [(eq? m 'cons-list) cons-list]
+           [(eq? m 'remove-ports) remove-ports]
+           [(eq? m 'add) add]))
+   dispatch)
+
+(define c-connections (make-connections '()))
+
+(define connections-s (make-semaphore 1)) ;; control access to connections
  ```
+ When the tcp-listener accepts a connection from a client, the associated input
+ output ports along with username  are added as an entry in ```make-connections``` via ```add``` function.
+ External functions can operate on the connections by securing the semaphore,
+ and then calling ```cons-list``` to expose the underlying list of connections.
+ ```remove-ports``` method is also available to remove input output ports from
+ managed connections.
+
+
  
- While using global objects is not a central theme in the course, it's necessary to show this code to understand
- the later examples.
  
-## 2. Selectors and Predicates using Procedural Abstraction
-
-A set of procedures was created to operate on the core ```drive-file``` object. Drive-files may be either
-actual file objects or folder objects. In Racket, they are represented as a hash table.
+## 2. Tracking received messages via objects and closures.
 
-```folder?``` accepts a ```drive-file```, inspects its ```mimeType```, and returns ```#t``` or ```#f```:
+The code below manages broadcast messages from one client to the rest. It wraps
+a list of strings inside an object that has functions similar to ```make-connections``` for
+exposing and manipulating the list from external functions. The code creates
+```make-messages``` global object and a semaphore to control access to it from
+various threads of execution.
 
 ```
-(define (folder? drive-file)
-  (string=? (hash-ref drive-file 'mimeType "nope") "application/vnd.google-apps.folder"))
+(define (make-messages messages)
+  (define (add message)
+    (set! messages (append messages (list message)))
+    messages)
+  (define (mes-list)
+    messages)
+  (define (remove-top)
+    (set! messages (rest messages))
+    messages)
+  (define (dispatch m)
+    (cond [(eq? m 'add) add]
+          [(eq? m 'mes-list) mes-list]
+          [(eq? m 'remove-top) remove-top]))
+  dispatch)
+
+(define c-messages (make-messages '()))
+
+(define messages-s (make-semaphore 1))  ;; control access to messages
 ```
 
-Another object produced by the Google Drive API is a list of drive-file objects ("```drive#fileList```"). 
-When converted by the JSON library,
-this list appears as hash map. 
+## 3. Using map to broadcast messages from client to clients
 
-```get-files``` retrieves a list of the files themselves, and ```get-id``` retrieves the unique ID
-associated with a ```drive#fileList``` object:
+The ```broadcast``` function is called repeatedly in a loop to extract a message
+from ```make-messages``` object, and send it to every other client. It uses the
+```make-connections``` objects to extract output port of a client. The ```map```
+routine is called on every client in the connections object to send it
+a message.
 
 ```
-(define (get-files obj)
-  (hash-ref obj 'files))
-
-(define (get-id obj)
-  (hash-ref obj 'id))
+(define broadcast
+  (lambda ()
+    (semaphore-wait messages-s)
+    (cond [(not (null? ((c-messages 'mes-list))))
+        (map
+            (lambda (ports)
+              (if (not (port-closed? (get-output-port ports)))
+                (begin 
+                    (displayln (first ((c-messages 'mes-list))) (get-output-port ports))
+                    (flush-output (get-output-port ports)))
+                (displayln-safe "Failed to broadcast. Port not open." error-out-s error-out)))
+            ((c-connections 'cons-list)))
+        (displayln-safe (first ((c-messages 'mes-list))) convs-out-s convs-out)
+        ;; remove top message from "queue" after broadcasting
+        ((c-messages 'remove-top))
+        ; debugging displayln below
+        ; (displayln "Message broadcasted")
+        ]) ; end of cond
+    (semaphore-post messages-s)))
 ```
-## 3. Using Recursion to Accumulate Results
+After the message is send, the message is removed from the "queue" via the
+```remove-top```.
 
-The low-level routine for interacting with Google Drive is named ```list-children```. This accepts an ID of a 
-folder object, and optionally, a token for which page of results to produce.
+The code snippet below creates a thread that iteratively calls ```broadcast```
+every interval, where interval(in secs) is defined by ```sleep-t```.
 
-A lot of the work here has to do with pagination. Because it's a web interface, one can only obtain a page of
-results at a time. So it's necessary to step through each page. When a page is returned, it includes a token
-for getting the next page. The ```list-children``` just gets one page:
+** note ** : ```sleep``` is very important for making Hermes behave gracefully
+in a system. Without it, it would be called at the rate derived from cpu clock
+rate. This raises cpu temperatures substantially, and make cause a pre-mature
+system shutdown.
 
 ```
-(define (list-children folder-id . next-page-token)
-  (read-json
-   (get-pure-port
-    (string->url (string-append "https://www.googleapis.com/drive/v3/files?"
-                                "q='" folder-id "'+in+parents"
-                                "&key=" (send drive-client get-id)
-                                (if (= 1 (length next-page-token))
-                                    (string-append "&pageToken=" (car next-page-token))
-                                    "")
-;                                "&pageSize=5"
-                                ))
-    token)))
+(thread (lambda ()
+              (displayln-safe "Broadcast thread started!")
+              (let loopb []
+                (sleep sleep-t)  ;; wait 0.2 ~ 0.5 secs before beginning to broadcast
+                (broadcast)
+                (loopb))))
 ```
-The interesting routine is ```list-all-children```. This routine is directly invoked by the user.
-It optionally accepts a page token; when it's used at top level this parameter will be null.
 
-The routine uses ```let*``` to retrieve one page of results (using the above ```list-children``` procedure)
-and also possibly obtain a token for the next page.
+## 4. Filtering a List of connections to find recipient of a whisper
 
-If there is a need to get more pages, the routine uses ```append``` to pre-pend the current results with 
-a recursive call to get the next page (and possibly more pages).
+I implemented a whisper functionality, where a user can whisper to any user in
+the chat room. The whisper message is only sent to specified user. To implement
+this i used ```filter``` over the connections, where the predicate tested whether the
+current list item matched that of a specific user.
 
-Ultimately, when there are no more pages to be had, the routine terminates and returns the current page. 
+'''
+(define whisper (regexp-match #px"(.*)/whisper\\s+(\\w+)\\s+(.*)" evt-t0))
 
-This then generates a recursive process from the recursive definition.
+[whisper
+                  (semaphore-wait connections-s)
+                  ; get output port for user
+                  ; this might be null
+                  (define that-user-ports
+                    (filter
+                     (lambda (ports)
+                       (if (string=? (whisper-to whisper) (get-username ports))
+                           #t
+                           #f))
+                     ((c-connections 'cons-list))))
+                  ; try to send that user the whisper
+                  (if (and (null? that-user-ports)
+                           #t) ; #t is placeholder for further checks
+                      (begin
+                        (displayln "User is unavailable. /color blue" out)
+                        (flush-output out))
+                      (begin
+                        (displayln (string-append "(whisper) "
+                                    (whisper-info whisper) (whisper-message whisper))
+                                   (get-output-port (car that-user-ports)))
+                        (flush-output (get-output-port (car that-user-ports)))))
+                  (semaphore-post connections-s)]
+'''
 
-```
-(define (list-all-children folder-id . next-page-token)
-  (let* ((this-page (if (= 0 (length next-page-token))
-                      (list-children folder-id)
-                      (list-children folder-id (car next-page-token))))
-         (page-token (hash-ref this-page 'nextPageToken #f)))
-    (if page-token
-        (append (get-files this-page)
-              (list-all-children folder-id page-token))
-        (get-files this-page))))
-```
-
-## 4. Filtering a List of File Objects for Only Those of Folder Type
+The snippet above is part of cond statement that tests contents of input from
+clients to determine what the client is trying wants/trying to do. The top-line
+is using regexes to determine whether the received message is a whisper or not.
 
-The ```list-all-children``` procedure creates a list of all objects contained within a given folder.
-These objects include the files themselves and other folders.
 
-The ```filter``` abstraction is then used with the ```folder?``` predicate to make a list of subfolders
-contained in a given folder:
 
-```
-(define (list-folders folder-id)
-  (filter folder? (list-all-children folder-id)))
-```
+## 5. Selectors for dealing with content of a whisper from clients
 
-## 5. Recursive Descent on a Folder Hierarchy
+Below are are three selectors that help abstract the contents of a whisper
+message.
 
-These procedures are used together in ```list-all-folders```, which accepts a folder ID and recursively
-obtains the folders at the current level and then recursively calls itself to descend completely into the folder
-hierarchy.
 
-```map``` and ```flatten``` are used to accomplish the recursive descent:
 
 ```
+; whisper selector for the username and message
+(define (whisper-info exp)
+  (cadr exp))
+
+(define (whisper-to exp)
+  (caddr exp))
+
+(define (whisper-message exp)
+  (cadddr exp))
 (define (list-all-folders folder-id)
   (let ((this-level (list-folders folder-id)))
     (begin
@@ -156,3 +230,7 @@ hierarchy.
       (append this-level
               (flatten (map list-all-folders (map get-id this-level)))))))
 ```
+
+```whisper-info``` retrieves the date-time and username info.
+```whisper-to``` retrieves the username of the intented recipient of a whisper.
+```whisper-message``` retrieves the actual whisper.