Merge pull request #34 from Shibin-Ez/master

docs: update roadmap documentation and refine Parson library guide fo…

Author: Shibin-Ez

docs/guides/references/parson.md

@@ -68,11 +68,11 @@ struct json_array_t {
 };
 ```
 
-In OOPS terms, `JSON_Value` is like a generic `Base Class` and `JSON_Object` and `JSON_Array` are like `Derived Class` objects. 
+You can assume `JSON_Value` as a generic *Base Class* and `JSON_Object` and `JSON_Array` as it's *Derived Class* objects. 
 
 ## JSON_Value Methods
 
-### `json_parse_file`
+### `json_parse_file()`
 Reads a JSON file and returns (`JSON_Value*`) that contains the entire content.
 
 ```c 
@@ -90,7 +90,7 @@ So after getting the `JSON_Value` struct object from `json_parse_file()`, method
 Since a JSON file can start with any valid data type (an object, an array, a string, or a number), the parser returns a generic `JSON_Value` struct object. We then must use the appropriate method to resolve it into the intended object or array.
 :::
 
-### `json_value_get_object`
+### `json_value_get_object()`
 
 Gets the main `JSON_Object` from a `JSON_Value`. Since our `xps_config.json` starts with `{}` we can use this function. If it had been starting with `[]` then that would imply the file starts as an array of object so we would have to use `json_value_get_array()` instead.
 
@@ -105,7 +105,7 @@ JSON_Object *json_value_get_object(const JSON_Value *value);
 
 Once you have a `JSON_Object`, you can get specific fields using the key name.
 
-### `json_value_get_array`
+### `json_value_get_array()`
 
 
 Gets the `JSON_Array` from a `JSON_Value`. This is used if your JSON file starts with an array (`[...]`) instead of an object.
@@ -119,7 +119,7 @@ JSON_Array *json_value_get_array(const JSON_Value *value);
   - `value`: The `JSON_Value` to check.
 - **Returns**: A pointer to a `JSON_Array`.
 
-### `json_value_free`
+### `json_value_free()`
 Frees the memory used by the parsed JSON.
 
 ```c
@@ -131,7 +131,7 @@ void json_value_free(JSON_Value *value);
 
 ## JSON_Object Methods
 
-### `json_object_get_string`
+### `json_object_get_string()`
 Gets a string value for a specific key.
 
 
@@ -144,7 +144,7 @@ const char *json_object_get_string(const JSON_Object *object, const char *name);
   - `name`: The key string (like `"server_name"`).
 - **Returns**: The string, or `NULL` if the key doesn't exist.
 
-### `json_object_get_number`
+### `json_object_get_number()`
 Gets a number value for a specific key.
 
 
@@ -154,7 +154,7 @@ double json_object_get_number(const JSON_Object *object, const char *name);
 
 - **Returns**: A number (which we often treat as an `int` or `size_t` in eXpServer for things like `port` or `workers`). Returns `0` on fail.
 
-### `json_object_get_boolean`
+### `json_object_get_boolean()`
 Gets a boolean (true/false) value for a specific key.
 
 
@@ -165,7 +165,7 @@ int json_object_get_boolean(const JSON_Object *object, const char *name);
 - **Returns**: `1` for true, `0` for false, or `-1` if it fails.
 <!-- - **Usage in eXpServer**: Used to check the `gzip_enable` setting. -->
 
-### `json_object_get_array`
+### `json_object_get_array()`
 Gets a JSON array for a specific key.
 
 
@@ -180,7 +180,7 @@ JSON_Array *json_object_get_array(const JSON_Object *object, const char *name);
 
 Once you have a `JSON_Array`, you can find out how big it is and loop through it.
 
-### `json_array_get_count`
+### `json_array_get_count()`
 Gets the total number of items in an array.
 
 
@@ -191,7 +191,7 @@ size_t json_array_get_count(const JSON_Array *array);
 - **Returns**: The size of the array.
 <!-- - **Usage in eXpServer**: Used as the limit in `for` loops when going through routes or servers. -->
 
-### `json_array_get_object`
+### `json_array_get_object()`
 Gets a `JSON_Object` at a specific position (index) in an array.
 
 
@@ -205,7 +205,7 @@ JSON_Object *json_array_get_object(const JSON_Array *array, size_t index);
 - **Returns**: The `JSON_Object` at that position.
 <!-- - **Usage in eXpServer**: Getting individual `"route"` items out of the main routes array. -->
 
-### `json_array_get_string`
+### `json_array_get_string()`
 Gets a string at a specific position in an array.
 
 

docs/roadmap/phase-1/stage-10.md

@@ -300,7 +300,7 @@ void xps_pipe_destroy(xps_pipe_t *pipe) {
 **`xps_pipe_is_writable`**
 
 - Checks if the buffer list length is below the buffer threshold (see `xps.h`), allowing new data to be written.
-  ::: details **expserver/src/core/xps_pipe.c - `xps_pipe_is_readable()`, `xps_pipe_is_writable()`**
+::: details **expserver/src/core/xps_pipe.c - `xps_pipe_is_readable()`, `xps_pipe_is_writable()`**
 
 ```c
 bool xps_pipe_is_readable(xps_pipe_t *pipe) { return /*fill this*/ }

docs/roadmap/phase-2/stage-14.md

@@ -88,39 +88,39 @@ struct xps_http_req_s {
 
   xps_http_method_t method_n;
 
-  char *request_line; // POST https://www.devdiary.live:3000/api/problems HTTP/1.1
+  char *request_line; // eg: POST https://www.devdiary.live:3000/api/problems HTTP/1.1
   u_char *request_line_start;
   u_char *request_line_end;
 
-  char *method; // POST
+  char *method; // eg: POST
   u_char *method_start;
   u_char *method_end;
 
-  char *uri; // https://www.devdiary.live:3000/api/problems?key=val
+  char *uri; // eg: https://www.devdiary.live:3000/api/problems?key=val
   u_char *uri_start;
   u_char *uri_end;
 
-  char *schema; // https
+  char *schema; // eg: https
   u_char *schema_start;
   u_char *schema_end;
 
-  char *host; // www.devdiary.live
+  char *host; // eg: www.devdiary.live
   u_char *host_start;
   u_char *host_end;
 
-  int port; // 3000
+  int port; // eg: 3000
   u_char *port_start;
   u_char *port_end;
 
-  char *path; // /api/problems?key=val
+  char *path; // eg: /api/problems?key=val
   u_char *path_start;
   u_char *path_end;
 
-  char *pathname; // /api/problems
+  char *pathname; // eg: /api/problems
   u_char *pathname_start;
   u_char *pathname_end;
 
-  char *http_version; // 1.1
+  char *http_version; // eg: 1.1
   u_char *http_major;
   u_char *http_minor;
 
@@ -422,12 +422,12 @@ int xps_http_parse_request_line(xps_http_req_t *http_req, xps_buffer_t *buff) {
 
       case RL_PATH:
         /*on ' ' - path ends, assign end of path,pathname,uri next state is RL_VERSION_START*/
-        /*on '?'or'&'or'='or'#' - assign end of pathname, next state is RL_PATHNAME*/
+        /*on '?'or'&'or'='or'#' - assign end of path, next state is RL_PATHNAME*/
         /*on CR or LF, fails*/
         break;
 
       case RL_PATHNAME:
-        /*on ' ' - assign end of uri,path, next state is RL_VERSION_START*/
+        /*on ' ' - assign end of uri,pathname, next state is RL_VERSION_START*/
         /*on CR or LF, fails*/
         break;
 
@@ -454,7 +454,7 @@ int xps_http_parse_request_line(xps_http_req_t *http_req, xps_buffer_t *buff) {
         break;
 
       case RL_VERSION_HTTP_SLASH:
-        /*on '1' - assign major, next state is RL_MAJOR, fails on all other inputs*/
+        /*on '1' - assign major, next state is RL_VERSION_MAJOR, fails on all other inputs*/
         break;
 
       case RL_VERSION_MAJOR:
@@ -785,12 +785,13 @@ const char *xps_http_get_header(vec_void_t *headers, const char *key) {
 
 ::: tip TRY
 
-- HTTP is case insensitive. Modify the code such that the comparison handles input key in a case insensitive way.
-  :::
+- TTP header names are case insensitive. Modify the code such that the comparison handles the input key in a case insensitive way.
+  
+:::
 
 - **`xps_http_serialize_headers()`**
 
-Serialize a list of HTTP headers(key-value pairs) into a buffer. The serialized headers will be formatted as a string, where each header is in the format - key: value\n. The function `sprintf` is used to format and store a string into a character buffer.
+Serialize a list of HTTP headers(key-value pairs) into a buffer. The serialized headers will be formatted as a string, where each header is in the format - `key: value\n`. The function `sprintf` is used to format and store a string into a character buffer.
 For each key value pair (eg. given below), an additional size of +5 characters are added to account for the colon (`:`), space (` `), newline (`\r\n`), and null terminator (`\0`).  
 
 For example consider the HTTP Request

docs/roadmap/phase-2/stage-15.md

@@ -148,7 +148,7 @@ xps_http_set_header(&(http_res->headers), "Access-Control-Allow-Origin", "*");
 
 `xps_http_res_serialize()` : used for serializing the whole response into a buffer. It is similiar to the serialize function used in http_request module.
 
-- First the headers are serialized using `xps_http_res_serialize()` , provided in the `xps_http` module and are stored into a temporary buffer.
+- First the headers are serialized using `xps_http_serialize_headers()` , provided in the `xps_http` module and are stored into a temporary buffer.
 - Then create a buffer instance for storing the serialized HTTP response. The length of the buffer is calculated by adding the lengths of each field in the struct `xps_http_res_s`.
 - Copy the response_line, header and body to the newly created buffer. Don’t forget to include a newline between response_line, headers and body.
 

docs/roadmap/phase-2/stage-16.md

@@ -70,7 +70,8 @@ This will create a parson directory inside `expserver/src/lib/` and download all
 
 :::tip READ
 
-Before proceeding further read about [Parson](/guides/references/parson)
+- Before proceeding further read about [Json](https://www.json.org/json-en.html) data exchange format
+- Read the specs of [Parson](/guides/references/parson) library
 
 :::
 
@@ -277,7 +278,7 @@ xps_config_t *xps_config_create(const char *config_path) {
 ```
 
 - `xps_config_destroy` : Cleans up and frees the memory allocated for the configuration object. Implement it by deallocating the servers and the corresponding listeners and routes. Also de-initialize the vectors.
-- `xps_config_lookup` : Performs a lookup to find the correct configuration based on an HTTP request (`xps_http_req_t`) and client details (`xps_connection_t`).
+- `xps_config_lookup` : Takes the parsed configuration, an incoming HTTP request, and the client connection as input. It determines the appropriate server and route for the request by first matching the client's listener and hostname against the configured servers, then selecting the best matching route using a longest prefix match on the request path. Based on the matched route type (`file_serve`, `reverse_proxy`, or `redirect`), it populates and returns an `xps_config_lookup_t` structure with the relevant fields. Sets `*error` to `E_FAIL` or `E_NOTFOUND` and returns `NULL` if no matching server or route is found.
 
 ```c
 xps_config_lookup_t *xps_config_lookup(xps_config_t *config, xps_http_req_t *http_req,
@@ -383,13 +384,13 @@ xps_config_lookup_t *xps_config_lookup(xps_config_t *config, xps_http_req_t *htt
 
 ### Core Module - Modifications
 
-- To `xps_core_s` struct, add `config` field. `xps_core_create()` takes config as argument.
-- Remove creating listeners while starting the server as the listeners are created during the configuration set-up itself.
+- To `xps_core_s` struct, add `config` field. Pass `config` as an argument to `xps_core_create()`.
+- Remove creating listeners while starting the server as the listeners are created during the configuration set-up itself (this will be done below, on modification to the `main.c`).
 
 ### Session Module - Modifications
 
-- Add the lookup field which is used to determine the type of the incoming request.
-- In the `session_process_request()` the lookup(to determine the type of request) is done and the request is processed with respect to its type.
+- Add a lookup field (`xps_config_lookup_t`) which is used to determine the type of the incoming request.
+- In the `session_process_request()` the lookup (to determine the type of request) is done and the request is processed with respect to its type.
 
 ```c
 /*config_lookup called*/
@@ -433,7 +434,7 @@ if (lookup->type == REQ_FILE_SERVE) {
 
 ### main.c
 
-Processes the command-line arguments to retrieve the configuration file path. The configuration is created which is followed by core creation.
+Processes the command-line arguments to retrieve the configuration file path. The configuration object is created by invoking the method of `xps_config` module. Then `core_create` function is invoked which handles creation of listeners and attaching it with core in accordance with the `config` object. And then starts the core.
 
 ```c
 int main(int argc, char *argv[]) {
@@ -655,4 +656,4 @@ Now, navigate to `http://localhost:8001/` in your browser. You will notice that
 
 ## Conclusion
 
-In this stage, we transitioned from a hardcoded server setup to a dynamic, configuration-driven architecture using JSON. By implementing the `config` module, eXpServer now supports multiple worker cores, reverse proxying, and URL redirects. While the server currently returns a 404 error when an index file is missing from a directory, we will resolve this in the next stage by implementing a dedicated directory module.
+In this stage, we transitioned from a hardcoded server setup to a dynamic, configuration-driven architecture using a JSON config file. By implementing the `config` module, eXpServer now supports reverse proxying and URL redirects. The server currently returns a 404 error when an index file is missing from a directory, we will resolve this in the next stage by implementing a dedicated directory module.

docs/roadmap/phase-2/stage-17.md

@@ -2,7 +2,7 @@
 
 ## Recap
 
-In the previous stages, we updated the server to handle HTTP messages. Stage 14 focused on implementing HTTP request parsing, while Stage 15 covered the construction of HTTP response messages. And in stage 16 we have implemented multiple cores, used a JSON file to set-up server configuration and implemented reverse proxy and URL redirecting in our webserver.
+In the previous stages, we updated the server to handle HTTP messages. Stage 14 focused on implementing HTTP request parsing, while Stage 15 covered the construction of HTTP response messages. And in stage 16 we have implemented config module, used a JSON file to set-up server configuration and implemented reverse proxy and URL redirecting in our webserver.
 
 ## Learning Objectives