README.md 3.62 KB
Newer Older
1
2
3
# HTTP.sh
Node.js, but `| sed s/Node/HTTP/;s/js/sh/`.

Dominika Liberda's avatar
Dominika Liberda committed
4
HTTP.sh is (by far) the most extensible attempt at creating a web framework in Bash, and (AFAIK) the only one that's actively maintained. Although I strive for code quality, this is still rather experimental and may contain bugs.
5

Dominika Liberda's avatar
Dominika Liberda committed
6
Originally made for Junction Stupidhack 2020; Created by [sdomi](https://sakamoto.pl/), [ptrcnull](https://ptrcnull.me/) and [selfisekai](https://selfisekai.rocks/).
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

## Quick Start

If you want to build a new webapp from scratch:

```
./http.sh init
./http.sh
```

If you're setting up HTTP.sh for an existing application:

```
git clone https://git.sakamoto.pl/laudom/ocw/ app # example repo :P
./http.sh
```
23
24
25

## Dependencies

Dominika Liberda's avatar
Dominika Liberda committed
26
27
28
- Bash (4.x should work, but we'll need 5.0 soon)
- [Ncat](https://nmap.org/ncat), not openbsd-nc, not netcat, not nc
- socat (because the above is slightly broken)
29
30
- pkill
- mktemp
31
- jq (probably not needed just yet, but it will be in 1.0)
32
- dd (for accounts, multipart/form-data and websockets)
33
- sha1sum, sha256sum, base64 (for accounts and simple auth)
34
35
36
37
38
39
- curl (for some demos)

## Known faults

- can't change the HTTP status code from Shell Server scripts. This could theoretically be done with custom vhost configs and some `if` statements, but this would be a rather nasty solution to that problem.
- `$post_multipart` doesn't keep original names - could be fixed by parsing individual headers from the multipart request instead of skipping them all
Dominika Liberda's avatar
Dominika Liberda committed
40
41
42
43
44
45
46
47
- it won't ever throw a 500, thus it fails silently

## Directory structure
- ${cfg[namespace]} (`app` by default)
	- ${cfg[root]} (`webroot` by default) - public application root
	- workers/ - scripts that execute periodically live there (see examples)
	- views/ - for use with HTTP.sh router
	- config.sh - application-level config file
48
- config
Dominika Liberda's avatar
Dominika Liberda committed
49
50
	- master.sh - main server config file - loaded on boot and with every request
	- host:port - if a file matching the Host header is found, HTTP.sh will load it request-wide
51
- src
Dominika Liberda's avatar
Dominika Liberda committed
52
	- server source files and modules
53
54
55
	- response
		- files corresponding to specific HTTP status codes
		- listing.sh (code 210) is actually HTTP 200, but triggered in a directory with autoindex turned on and without a valid `index.shs` file
56
57
58
- templates - section templates go here
- secret - users, passwords and other Seecret data should be stored here
- storage - random data storage for your webapp
59
60
61

## Variables that we think are cool!

62
63
![](https://f.sakamoto.pl/d6584c01-1c48-42b9-935b-d9a89af4e071file_101.jpg)

Dominika Liberda's avatar
Dominika Liberda committed
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
- get_data - holds data from GET parameters
	- /?test=asdf -> `${get_data[test]}` == `"asdf"`
- params - holds parsed data from URL router
	- /profile/test (assuming profile/:name) -> `${params[name]}` == `"test"` 
- post_data - same as above, but for urlencoded POST params
	- test=asdf -> `${post_data[test]}` == `"asdf"`
- post_multipart - contains paths to uploaded files from multipart/form-data POST requests. **WARNING**: it doesn't hold field names yet, it relies on upload order for identification
	- first file (in upload order) -> `cat ${post_multipart[0]}`
	- second file -> `cat ${post_multipart[1]}`
- r - misc request data
	- authorization
	- content_boundary
	- content_boundary
	- content_length
	- content_type
	- headers
	- host
	- host_portless
	- ip
	- post
	- proto
	- status
	- uri
	- url
	- user_agent
	- view
	- websocket_key
- cfg - server and app config - see `config/master.sh` for more details
	
## Fun stuff

- To prevent running malicious scripts, by default only scripts with extension `.shs` can be run by the server, but this can be changed in the config.
- ${cfg[index]} ignores the above - see config/master.sh
- Trans rights!
- SHS stands for Shell Server.