tinylogs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nikita Medvedev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# tinylogs
+
+A tiny, self-hosted **central log receiver + live dashboard**. Apps push log lines
+over HTTP; you watch them in a fast, dense browser dashboard with label filtering.
+Single Node process, single SQLite file. Runs anywhere `npx` runs.
+
+## Quick start
+
+```bash
+npx tinylogs init      # wizard: port, admin user/pass, retention → writes tinylogs.config.json + prints an ingest token
+npx tinylogs start     # runs the receiver + dashboard (default http://127.0.0.1:4700)
+```
+
+Open the dashboard, log in with the admin user you created.
+
+Non-interactive init (CI/containers):
+
+```bash
+TINYLOGS_PASSWORD=hunter2 npx tinylogs init --yes --port 4700
+```
+
+## Sending logs
+
+Anything that can make an HTTP request can send logs. `service` and `message` are
+required; `labels` are arbitrary string key/values. `level` is just a label with
+special coloring.
+
+```bash
+curl -XPOST http://localhost:4700/ingest \
+  -H "Authorization: Bearer <INGEST_TOKEN>" \
+  -H "Content-Type: application/json" \
+  -d '{"service":"debtors-bot","message":"reminder sent","labels":{"level":"info","user":"12345"}}'
+```
+
+Batch by sending an array. Response: `{"accepted": N}` (400 if `service`/`message`
+missing, 401 if the token is wrong).
+
+### Node client
+
+```ts
+import { TinyLogsClient } from 'tinylogs/client';
+
+const logs = new TinyLogsClient({
+  url: 'http://localhost:4700',
+  token: process.env.TINYLOGS_TOKEN!,
+  service: 'debtors-bot',
+});
+
+logs.info('reminder sent', { user: '12345' });
+logs.error('boom', { user: '12345' });
+// fire-and-forget: never throws, never blocks your app, batches automatically.
+await logs.close(); // flush on shutdown
+```
+
+## Configuration
+
+`tinylogs.config.json` (created by `init`, in the current directory by default):
+
+| Field | Meaning | Default |
+|-------|---------|---------|
+| `port` / `host` | Listen address | `4700` / `127.0.0.1` |
+| `dbPath` | SQLite file (relative to the config file) | `tinylogs.db` |
+| `retentionDays` | Delete logs older than this | `14` |
+| `maxSizeMB` | Cap the DB file; oldest rows pruned first | `500` |
+| `bufferSize` | In-memory live-tail buffer | `2000` |
+| `sessionSecret` / `ingestTokenHash` | Generated at init — do not edit | — |
+
+Override the config location with `--config <path>` or `TINYLOGS_CONFIG`.
+Rotate the ingest token with `npx tinylogs rotate-token`.
+
+## Security
+
+- **No default password** — `init` forces you to set one.
+- **TLS is delegated to a reverse proxy.** tinylogs serves plain HTTP; put nginx or
+  Caddy in front for HTTPS. Example (Caddy):
+
+  ```
+  logs.example.com {
+    reverse_proxy 127.0.0.1:4700
+  }
+  ```
+
+- Dashboard auth is a signed **httpOnly session cookie**; `/api/*` and `/ws` require it.
+- `/api/login` is rate-limited against brute force.
+- The ingest token is a separate shared secret, stored **hashed**; shown only once.
+
+## How it works
+
+- **Storage:** SQLite in WAL mode. `logs` holds each line (labels as JSON for one-read
+  render); `log_labels` explodes labels for index-backed `key=value` filtering.
+- **Live tail:** a bounded in-memory ring buffer seeds new browser tabs and feeds the
+  WebSocket stream. The DB is the source of truth for history + search.
+- **Retention:** a background task prunes by age and by size (whichever hits first) and
+  VACUUMs; failures are logged, never fatal.
+
+## Non-goals
+
+Not a clustered/distributed store, not metrics/tracing, not multi-tenant SaaS. One node,
+one SQLite file, one admin.
+
+## License
+
+MIT © 2026 Nikita Medvedev