\n Series: \n \n
\n\n```\n\nThe returned value of the code inside a scoped code block will show up in the page.\n\n### HTML template tags\nDuring parsing, code within `` will be evaluated.\nThe value of the code will be displayed on the page.\n\nThese tags should be preferred only for displaying values from variables.\n\n#### Example:\n```HTML\n\n \nNames:
\nUID:
\n\n```\n\nIn the above code, `NAME` and `UID.toUpperCase()` are used inside the template tags.\n\n## The configuration file\nA file named `config.json` placed at the root of server resources will contain configurations for the server.\n\nAny property specified in `config.json` fully overwrites default config values.\nTherefore, if the property to be specified is an array (or object like [matchConfig](#8-matchconfig)), then all its properties must be specified in the config.json file.\nOtherwise, the server might crash.\n\n#### Bad\nIf you don't want to expose `/config.json`, `/server.log` and `/.builds` directories, you shouldn't do this.\n\nThey contain information about your server, your server code, etc, and you don't want to expose them.\n\n```JSON5\n\"forbidden\": [\n \"/private/.*\",\n \"/data/.*\",\n \"/assets/.*\"\n]\n```\n\n#### Good\n```JSON5\n\"forbidden\": [\n \"/config\\\\.json\", // default\n \"/server\\\\.log\", // default\n \"/\\\\.builds/.*\", // default\n \"/private/.*\",\n \"/data/.*\",\n \"/assets/.*\"\n]\n```\n\n## Config properties\nThe server can understand only the following properties.\n\nIf you declare a property the server doesn't understand, it won't cause any errors.\nYou will be able to access those properties from the `$_CONFIG` object in your JSHP code.\n\n### 1. defaultHeaders\nHeaders specified here are written to every response.\n\n**Default:** `\"defaultHeaders\": {}` i.e. an empty object.\n\n### 2. logPath\nPath to server log file. Logging can be turned off by setting property value to empty string.\n\n#### Format:\n```\n[date time][Functions -> Logger.info(any)](#functions)).\n\nBeyond this length, the message is printed below.\n\n**Default:** `\"inlineLogLength\": \"96\"`\n\n### 4. indexFile\nPath to the index file if requested path is a directory.\n\nDirectories must end with a `/` in the get request.\nOtherwise they are considered files, unless [trailingSlashes](#7-trailingSlashes) is disabled.\n\n#### Example\nIf `\"indexFile\": \"main.jshp.html\"` then for request\n```\nGET /msg/ HTTP/1.1\nHost: xyz.net\nConnection: close\n\n```\nthe server serves the file `/msg/main.jshp.html`.\nBut as the file has a `.jshp.html` extension, it gets executed.\n\n**Default:** `\"indexFile\": \"index.jshp.html\"`.\n\n### 5. timeoutSec\nRequest times out with `500` after a specified number of seconds.\nThis timeout dictates how long a JSHP code is allowed to be parsed.\nIf JSHP code contains an infinite loop (or similar), it'll be killed after specified seconds.\n\n**Default:** `\"timeoutSec\": 10`\n\n### 6. execExtensions\nExtensions of files that needs to be parsed for executing JSHP codes.\n\n#### Example\nIf `\"execExtensions\": [ \".jshp.html\" ]` then only files ending with those extensions will get parsed.\n\nOn parsing, if the parser finds any executable JavaScript, it'll get executed, and any non-executable part will be copy-pasted.\n\n**Default:** `\"execExtensions\": [ \".jshp.html\" ]`\n\n### 7. trailingSlashes\nTrailing slashes after a directory isn't required if set to false. This property is a syntactic sugar for [noExtension](#8-noExtension).\n\n**Default:** `\"trailingSlashes\": true`\n\n### 8. noExtension\nIf requested path is a file and has no extension, server will look for a file having requested name and one of these extensions.\n\n#### Example\nIf `\"noExtension\": [ \".jshp.html\" ]` then for request\n```\nGET /msg/main HTTP/1.1\nHost: xyz.net\nConnection: close\n\n```\nthe server serves the file `/msg/main.jshp.html`.\nThat is because `main.jshp.html` is a file having name `main` and ending with and extension specified in `noExtension`.\nBut as the file has a `.jshp.html` extension, it gets executed.\n\nIf specified extension is a `'/'`, then for the directory `/msg/`, trailing slash will not be required.\n\n#### Example\nIf `\"noExtension\": [ \"/\", \".jshp.html\" ]` and `\"indexFile\": \"main.jshp.html\"` then for request\n```\nGET /msg HTTP/1.1\nHost: xyz.net\nConnection: close\n\n```\nthe server serves the file `/msg/main.jshp.html`.\n\nThis is because a `'/'` is also treated as an extension, but the path is a directory.\nFor it to work, the index file of the directory must be specified in [indexFile](#4-indexFile).\n\n**Default:** `\"noExtension\": [ \".jshp.html\" ]`\n\n### 9. matchConfig\nThis property specifies how regexes in the config file are handled.\nNot all config properties support regexes.\nIf a property supports regex, it'll have the word `REGEXSUP` in its section of description.\n\n#### Default\n```JSON5\n\"matchConfig\": {\n \"matchFromStart\": true,\n \"matchTillEnd\": true\n}\n```\nIf the default is kept then for properties that support regex, `matchFromStart` adds `^` to the beginning of the regex and `matchTillEnd` adds `$` to its end.\n\n#### Example\nIf config is\n```JSON5\n\"rewrites\": [\n {\n \"req\": \"/chat.*\",\n \"src\": \"/messaging/chat/index.jshp.html\"\n }\n]\n```\nthen, `/chat.*` is turned into the regex `/^\\/chat.*\\/$/`.\nThis means any path starting with `/chat` is rewritten to the `src`.\n\nLearn more about rewriting paths in [rewrites](#14-rewrites) section.\n\nIf `matchTillEnd` is disabled, `/chat.*` would be turned into the regex `/^\\/chat.*\\//`.\n\n### 10. buildDir\nPath to directory under resource root where compiled codes are kept.\n\n#### Caution\nMake sure your build directory is listed in [forbidden](#13-forbidden) to prevent clients from reading your code.\n\nOtherwise, quite understandably, your source code will get leaked.\n\n**Default:** `\"buildDir\": \"/.builds/\",`\n\n### 11. hotCompile\nIf `true`, JSHP files will be compiled every time that file is requested. Suitable for testing and debugging.\n\n**Default:** `\"hotCompile\": false`\n\n### 12. compileOnStart\nIf `true`, JSHP code will be compiled to executable JS during server startup.\n\n**Default:** `\"compileOnStart\": false`\n\n### 13. forbidden\nIf any of these files are requested, response is `403`.\n\n**Note:** This property supports regexes (`REGEXSUP`).\n\n#### Default\n```JSON5\n\"forbidden\": [\n \"/config\\\\.json\",\n \"/server\\\\.log\",\n \"/\\\\.builds/.*\"\n]\n```\n\n### 14. rewrites\nFor a specified path, server sends response from another specified path.\n\n#### Example\nIf config is\n```JSON5\n\"rewrites\": [\n {\n \"req\": \"/chat\",\n \"src\": \"/messaging/chat/index.jshp.html\"\n }\n]\n```\nthen for request\n```\nGET /chat HTTP/1.1\nHost: xyz.net\nConnection: close\n\n```\nthe server serves the file `/messaging/chat/index.jshp.html`.\n\nIt is not a redirection, so it'll result in `200` if `/messaging/chat/index.jshp.html` is a valid request path.\n\n**Note:** Property `req` of this property supports regexes (`REGEXSUP`).\n\n**Default:** `\"rewrites\": []` i.e. an empty array.\n\n### 15. redirects\nFor a specified path, server sends response `3xx` with a `Location` header.\n\n#### Example\nIf config is\n```JSON5\n\"redirects\": [\n {\n \"req\": \"/chat\",\n \"src\": \"/messaging/chat/index.jshp.html\",\n \"status\": 301\n }\n]\n```\nthen for request\n```\nGET /chat HTTP/1.1\nHost: xyz.net\nConnection: close\n\n```\nthe server responds with\n```\nHTTP/1.1 301 Moved Parmanently\nLocation: /messaging/chat/index.jshp.html\n.\n.\n.\n\n```\nThis request is a redirection, so it'll result in `3xx`.\n\n**Default:** `\"redirects\": []` i.e. an empty array.\n\n**Note:** Property `req` of this property supports regexes (`REGEXSUP`).\n\n**Note:** Redirects work for external domains as well.\nBut redirects are not open to the client.\nThe server redirects only if you specify it in `config.json`.\n\n**Note:** If a path is present in both `rewrites` and `redirects`, the server will\ndo a rewrite.\n\nThis is because a request is first checked for rewrites and then for redirects.\n\n### 16. errFiles\nFor a specified HTTP error, a specified file is sent as a response.\n\n#### Example\nIf config is\n```JSON5\n\"errFiles\": {\n \"404\": \"/404.jshp.html\",\n \"403\": \"/403.jshp.html\"\n}\n```\nthen for a `404` error, server serves the file `/404.jshp.html`.\n\nIf the specified file doesn't exist, an empty response is sent.\n\n**Default:** `\"errFiles\": {}` i.e. an empty object.\n\n### 17. respondInChunks\nIf `true`, server will use `response.write` to send responses.\nFor every `echo`, server does this depending on the next 2 properties.\n\nBy default, it's kept off.\nAs a result, the server waits for the entire page to be generated server side, and then it uses `response.end` to serve the page.\n\n#### Drawbacks\n- You have to use `setStatusCode()`, `setHeader()` and `setCookie()` before you've written any HTML or echoed something.\n- Content-Length header won't be set.\n- Has no practical improvements.\n\n**Default:** `\"respondInChunks\": false`\n\n### 18. chunkLimit\nCharacter / byte limit beyond which echoed data gets broken into pieces.\n\n**Default:** `\"chunkLimit\": 200`\n\n### 19. chunksPerEcho\nNumber of chunks in which echoed data is to be split.\n\n**Default:** `\"chunksPerEcho\": 2`\n\n## Hidden config\nThese config properties are auto generated by the server during startup and on calling `Server.reloadConfig()`.\n\nSpecifying these properties in `config.json` has no effect as the server will just overwrite any of these properties.\n\n### 1. host\nServer host, collected from the `host:port` argument.\n\n### 2. port\nServer port, collected from the `host:port` argument.\n\n### 3. resRoot\nA string containing the path to server resources, collected from the `path` argument.\n\n### 4. rewriteList\nIt's an array of all those paths that are to be rewritten.\n\n### 5. redirectList\nIt's an array of all those paths that are to be redirected.\n\n### 6. srcMapping\nIt's an object mapping sources (jshp files) to their respective JavaScript compiled files.\nIt is generated when JSHP code is compiled.\n\n## Global variables\n- `$_ENV` - Object, Stores system environment variables\n- `$_CONFIG` - Object, Stores server configuration data\n- `$_RES_ROOT` - String, Stores the path to server resources\n- `$_REQUEST` - Object, Some request data\n- `$_HEADERS` - Object, Stores headers of request\n- `$_COOKIES` - Object, Not yet implemented\n- `$_GET` - Object, Stores url parameters\n- `$_POST` - Object, Not yet implemented\n- `$_SERVER` - Object, Stores some server variables, work in progress\n- `$_SESSION` - Object, Not yet implemented\n\n## Functions\n- **setHeader(name, value)** - Sets header of current response\n- **setStatusCode(code)** - Sets response code\n- **setCookie(name, value)** - Not yet implemented\n- **writeToResponse(string or Buffer)** - Writes some data directly to response\n- **endResponse(string or Buffer, encoding)** - Similar to http module's `response.end()`;\n- **Logger.info(any)** - Write an info to the console\n- **Logger.error(any)** - Write an error to the console\n- **Logger.warn(any)** - Write a warning to the console\n- **echo(str)** - Displays text/HTML\n- **Message.echo(str, color?)** - Displays text/HTML within a color bordered box\n- **Message.warn(str)** - Displays text/HTML within a tangerine bordered box\n- **Message.error(str)** - Displays text/HTML within a red bordered box\n- **File.read(path, callback)** - Synchronously reads file, optional callback, returns a Buffer\n- **File.write(path, data, callback)** - Asynchronously writes file, optional callback, data is a Buffer\n- **ResponseCode.list()** - Get a list of response codes with their status messages.\n- **ResponseCode.getMessage(number)** - Get status messages of a response code.\n\n## Special functions\n- **prequire(path)** - Loads a module for the `jshp` file.\n- **nodejsinfo()** - Displays some server information.\n- **jshpinfo()** - Same as `nodejsinfo`.\n- **getStatusCode()** - Get status code of current page.\n- **Server.reloadConfig()** - Reload config data from config.json\n- **Server.fileCompile(path)** - Selectively recompile a file.\n- **Server.recompile()** - Re-run compilation to include source code changes\n- **Server.putResHash(algorithm)** - Writes hash of response to header `x-response-hash`, algorithm is `md5` by default.\n\n## Importing modules\nFor `jshp` files, `require` will not work. `require` will attempt to load modules relative to directory of the executable.\nTo load modules relative to the server resources root, a specialised function `prequire` is provided.\n\nSyntax\n```HTML\n\n```\n\nNote that paths to prequire (starting with `js:`, `jshp:` and `/`) are evaluated relative to `$_RES_ROOT`.\n\nNote that the `js:` prefix is optional for loading JavaScript files.\n\nBut the `jshp:` prefix is absolutely necessary if another `jshp` file is to be loaded.\n\nOtherwise the server will attempt to run that `jshp` file as JavaScript, and crash and burn.\n\n## Async and await\nNote that certain functions return promises. They are\n- `getStatusCode()`\n- `Server.reloadConfig()`\n- `Server.fileCompile(path)`\n- `Server.recompile()`\n\nWithout proper promise handling, you might get errors.\nIt is recommended that you use `await` keyword for a clean looking code.\n\n#### Example\n```HTML\n\n```\n\nIf you're wondering why you can use await without creating another async function to containing it,\nthat's because behind the scenes, the whole JSHP code runs in an async function.\n\n## Module variables\n- `HTTP` - NodeJS `http` module\n- `URL` - NodeJS `url` module\n- `PATH` - NodeJS `path` module\n- `FS` - NodeJS `fs` module\n\n## Security bug 1\nRefer to [GHSA-8r4g-cg4m-x23c](https://github.com/advisories/GHSA-8r4g-cg4m-x23c).\n- `node-static` v <= 0.7.11 is affected.\n- as of 25th Dec, 2021, no fixed npm package is available.\n- The issue was fixed in `node-static PR #227`.\n- As a workaround for JSHP, a request is first checked for `%00`.\n","readmeFilename":"README.md"}