commit 1271880

add daemon, developer, config documentation

i love writing documentation ( >:c )

 1@@ -0,0 +1,84 @@
 2+.Dd January 28, 2026
 3+.Dt PARADOS 1
 4+.Os
 5+.Sh NAME
 6+.Nm parados
 7+.Nd simple (HTTP) media server
 8+.Sh SYNOPSIS
 9+.Nm parados
10+.Sh DESCRIPTION
11+.Nm
12+is a minimal (HTTP) media server used to serve local audio and video
13+files over a network.
14+It provides a small and stable interface designed to be used by
15+external clients such as media players or web frontend interfaces.
16+.Pp
17+The server scans a directory tree at startup and exposes the contents
18+through its simple HTTP API.
19+Each file is assigned a hashed identifier derived from its relative
20+path.
21+.Pp
22+.Nm
23+does not provide a graphical interface.
24+All user interaction is expected to occur through clients.
25+.Sh OPERATION
26+On startup,
27+.Nm
28+performs the following steps:
29+.Bl -enum -compact
30+.It
31+Load configuration from
32+.Pa /etc/parados.conf,
33+or 
34+.Pa ./parados.conf
35+if the system-wide file is not present.
36+.It
37+Scan the configured media directory and build a library.
38+.It
39+Bind to the configured address and port.
40+.It
41+Accept HTTP connections and serve requests.
42+.El
43+.Pp
44+Each incoming connection is handled independently.
45+The server is designed for minimising complexity as opposed to concurrency.
46+.Sh HTTP INTERFACE
47+The following endpoints are provided:
48+.Bl -tag -width Ds
49+.It Pa /ping
50+Return a plain text response to indicate that the server is running.
51+.It Pa /library
52+Return a JSON document describing the media library.
53+.It Pa /meta/<id>
54+Return metadata for a single media item.
55+.It Pa /stream/<id>
56+Stream the raw contents of a media file.
57+Byte range requests are supported.
58+.It Pa /queue
59+Return an M3U playlist containing all accessible media items.
60+.El
61+.Pp
62+Authentication may be required depending on configuration.
63+.Sh AUTHENTICATION
64+.Nm
65+supports HTTP Basic authentication.
66+Authentication is optional and configured through
67+.Xr parados.conf 5 .
68+.Pp
69+If no users are defined, requests are served without authentication.
70+If one or more users are defined, all requests apart from
71+.Pa /ping
72+require valid credentials.
73+.Pp
74+Access to files is restricted per user based on configured allow-list.
75+.Sh CONFIGURATION
76+Configuration is read from
77+.Xr parados.conf 5 .
78+.Sh EXIT STATUS
79+.Ex -std
80+.Sh SEE ALSO
81+.Xr parados.conf 5 ,
82+.Xr parados-protocol 7
83+.Sh AUTHORS
84+.An Abhinav Prasai
85+

  1@@ -0,0 +1,117 @@
  2+.Dd January 28, 2026
  3+.Dt PARADOS 7
  4+.Os
  5+.Sh NAME
  6+.Nm parados
  7+.Nd HTTP protocol for the parados media server
  8+.Sh DESCRIPTION
  9+The
 10+.Nm
 11+protocol describes the HTTP interface provided by
 12+.Xr parados 1 .
 13+It is intended for simple clients and scripts.
 14+.Pp
 15+The protocol uses HTTP/1.1.
 16+Each request is handled on a separate connection, which is closed after
 17+the response.
 18+Persistent connections are not supported.
 19+.Pp
 20+Media items are identified by 64-bit identifiers encoded as 16 hexadecimal
 21+digits.
 22+.Sh REQUESTS
 23+All endpoints accept
 24+.Cm GET
 25+and
 26+.Cm HEAD
 27+requests.
 28+The server also accepts
 29+.Cm OPTIONS
 30+for CORS preflight.
 31+.Sh AUTHENTICATION
 32+If one or more users are configured,
 33+HTTP Basic authentication is required for all endpoints except
 34+.Pa /ping .
 35+.Pp
 36+Credentials are provided using the
 37+.Cm Authorization
 38+header.
 39+.Pp
 40+If no users are configured, authentication is disabled.
 41+.Sh ENDPOINTS
 42+.Bl -tag -width Ds
 43+.It Pa /ping
 44+Health check endpoint.
 45+Returns HTTP 200 with a short plain text body.
 46+.It Pa /library
 47+Return the media library as JSON.
 48+Each entry contains an item identifier and a relative path.
 49+.Pp
 50+Response format:
 51+.Bd -literal -offset indent
 52+{ "proto": 1, "items": [ { "id": "...", "path": "..." } ] }
 53+.Ed
 54+.It Pa /meta/{id}
 55+Return metadata for a single item.
 56+The response includes the item identifier, path, size in bytes, and MIME
 57+type.
 58+.It Pa /stream/{id}
 59+Stream the contents of a media item.
 60+Supports byte range requests using the
 61+.Cm Range
 62+header.
 63+.Pp
 64+Valid ranges return HTTP 206.
 65+Invalid ranges return HTTP 400 or HTTP 416.
 66+.It Pa /queue
 67+Return an M3U playlist containing stream URLs for all permitted items.
 68+.Pp
 69+If the request includes a
 70+.Cm Host
 71+header, it is used to construct playlist URLs.
 72+.El
 73+.Sh RESPONSES
 74+The server sets
 75+.Cm Content-Type
 76+based on file extension.
 77+Unknown types default to
 78+.Cm application/octet-stream .
 79+.Pp
 80+Most responses include
 81+.Cm Content-Length .
 82+Streaming responses may omit it.
 83+.Sh STATUS CODES
 84+.Bl -tag -width Ds
 85+.It Cm 200
 86+Request succeeded.
 87+.It Cm 204
 88+No content.
 89+.It Cm 206
 90+Partial content.
 91+.It Cm 400
 92+Bad request.
 93+.It Cm 401
 94+Authentication required or failed.
 95+.It Cm 404
 96+Resource not found or not permitted.
 97+.It Cm 405
 98+Method not allowed.
 99+.It Cm 416
100+Requested range not satisfiable.
101+.It Cm 500
102+Internal server error.
103+.El
104+.Sh VERSIONING
105+JSON responses include a
106+.Cm proto
107+field indicating the protocol version.
108+Clients should reject unknown versions.
109+.Sh NOTES
110+The protocol does not provide sessions, persistent connections,
111+transcoding, or server-side state.
112+All higher-level behavior is handled by the client.
113+.Sh SEE ALSO
114+.Xr parados 1 ,
115+.Xr parados.conf 5
116+.Sh AUTHORS
117+.An Abhinav Prasai
118+

  1@@ -0,0 +1,186 @@
  2+.Dd January 28, 2026
  3+.Dt PARADOS.CONF 5
  4+.Os
  5+.Sh NAME
  6+.Nm parados.conf
  7+.Nd configuration file for parados
  8+.Sh DESCRIPTION
  9+The
 10+.Nm
 11+file configures
 12+.Xr parados 1 .
 13+.Pp
 14+The file format is line-oriented.
 15+Each non-empty, non-comment line is a key/value pair int he form:
 16+.Bd -literal -offset indent
 17+key=value
 18+.Ed
 19+.Pp
 20+Whitespace around keys and values are ignored.
 21+Lines beginning with
 22+.Sq #
 23+are comments and are ignored.
 24+Invalid keys are ignored.
 25+.Sh FILES
 26+.Bl -tag -width Ds
 27+.It Pa /etc/parados.conf
 28+System-wide configuration file.
 29+.It Pa ./parados.conf
 30+Fallback configuration file in the current working directory.
 31+.El
 32+.Sh PARAMETERS
 33+.Bl -tag -width Ds
 34+.It Ic media_dir
 35+Directory containing all media files.
 36+The library is built by recursively scanning this directory at startup.
 37+.Pp
 38+Example:
 39+.Bd -literal -offset indent
 40+media_dir=/path/to/media
 41+.Ed
 42+.It Ic server_addr
 43+Address to bind the HTTP server to.
 44+Use
 45+.Cm 127.0.0.1
 46+to listen on the local host only.
 47+This is also recommended if you are soley using a WebUI interface
 48+hosted from the same device as exposing the server to the whole
 49+network may uncessesarily open your server to danger.
 50+Use
 51+.Cm 0.0.0.0
 52+to listen on all IPv4 interfaces.
 53+.Pp
 54+Example:
 55+.Bd -literal -offset indent
 56+server_addr=0.0.0.0
 57+.Ed
 58+.It Ic server_port
 59+TCP port to listen on.
 60+.Pp
 61+Example:
 62+.Bd -literal -offset indent
 63+server_port=8088
 64+.Ed
 65+.It Ic verbose_log
 66+Enable or disable verbose logging.
 67+Accepted values are
 68+.Cm 1 ,
 69+.Cm 0 ,
 70+.Cm true ,
 71+.Cm false ,
 72+.Cm yes ,
 73+and
 74+.Cm no
 75+(case-insensitive).
 76+.Pp
 77+Example:
 78+.Bd -literal -offset indent
 79+verbose_log=true
 80+.Ed
 81+.It Ic cors_origin
 82+Configure Cross-Origin Resource Sharing (CORS) for web clients.
 83+.Pp
 84+If empty, CORS header is sent.
 85+If set to
 86+.Cm * ,
 87+all origins are allowed, otherwise, the value is interpreted as a
 88+comma-separated list of allowed origins (clients that can interact
 89+over the web).
 90+.Pp
 91+Example:
 92+.Bd -literal -offset indent
 93+cors_origin=http://127.0.0.1:8000
 94+.Ed
 95+.El
 96+.Sh AUTHENTICATION
 97+Authentication entries are specified using repeated groups of the keys
 98+.Ic user ,
 99+.Ic pass ,
100+and
101+.Ic allow .
102+.Pp
103+If no
104+.Ic user
105+entries are present, authentication is disabled and all files are
106+accessible.
107+If one or more users are present, HTTP Basic authentication is required
108+for all requests (except
109+.Pa /ping ).
110+.Pp
111+Each
112+.Ic user
113+starts a new entry.
114+The following
115+.Ic pass
116+and
117+.Ic allow
118+lines apply to that user until the next
119+.Ic user
120+line.
121+.Bl -tag -width Ds
122+.It Ic user
123+Set the username for a new authentication entry.
124+.Pp
125+Example:
126+.Bd -literal -offset indent
127+user=glenda
128+.Ed
129+.It Ic pass
130+Set the password for the most recently declared user.
131+If empty, the account is passwordless and accepts only an empty password.
132+.Pp
133+Example:
134+.Bd -literal -offset indent
135+pass=secret
136+.Ed
137+.It Ic allow
138+Add an allowed path prefix for the most recently declared user.
139+Multiple
140+.Ic allow
141+directives may be used.
142+.Pp
143+A value of
144+.Cm *
145+allows all paths.
146+Otherwise, the value must match the beginning of a file's relative path.
147+The match allows directory boundaries.
148+.Pp
149+Example:
150+.Bd -literal -offset indent
151+allow=Media/
152+allow=Music/
153+.Ed
154+.El
155+.Sh EXAMPLES
156+Minimal configuration:
157+.Bd -literal -offset indent
158+media_dir=/path/to/media
159+server_addr=127.0.0.1
160+server_port=8088
161+verbose_log=true
162+cors_origin=
163+.Ed
164+.Pp
165+Two users with separate access:
166+.Bd -literal -offset indent
167+user=glenda
168+pass=pass123
169+allow=Media/
170+allow=Music/
171+
172+user=bob
173+pass=
174+allow=TV/NBA/
175+.Ed
176+.Pp
177+Single passwordless admin user with full access:
178+.Bd -literal -offset indent
179+user=admin
180+pass=
181+allow=*
182+.Ed
183+.Sh SEE ALSO
184+.Xr parados 1
185+.Sh AUTHORS
186+.An Abhinav Prasai
187+