Feat/optimise

.dockerignore

@@ -0,0 +1,9 @@
+node_modules
+lib
+admin-ui/node_modules
+admin-ui/dist
+.env
+*.log
+.git
+docs
+test

.env.example

@@ -8,4 +8,11 @@ SECURE=false
 SSL_KEY=
 SSL_CERT=
 # Timeout for cache service. Default is 5000 ms
-TIMEOUT=7000
+TIMEOUT=7000
+
+# Admin API shared secret for /__osham/admin/* endpoints
+OSHAM_ADMIN_SECRET=
+# Allow insecure admin access from localhost only (development/test only)
+OSHAM_ADMIN_ALLOW_INSECURE_LOCAL=false
+# Maximum accepted admin JSON request body size in bytes (default 1048576 = 1 MiB)
+OSHAM_ADMIN_MAX_BODY_BYTES=1048576

.github/workflows/ci.yml

@@ -32,3 +32,20 @@ jobs:
       - name: Test
         run: npm test
 
+  build-admin-ui:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      - name: Install admin-ui dependencies
+        run: cd admin-ui && npm ci
+
+      - name: Build admin-ui
+        run: cd admin-ui && npm run build

.gitignore

@@ -62,7 +62,16 @@ typings/
 
 lib
 
+admin-ui/dist
+admin-ui/src/**/*.js
+admin-ui/src/**/*.d.ts
+admin-ui/vite.config.js
+admin-ui/vite.config.d.ts
+admin-ui/tsconfig.tsbuildinfo
+
 cache-config.yml
+.osham-admin-history/
+.osham-admin-audit.jsonl
 
 .vscode
 .temp

Dockerfile

@@ -0,0 +1,28 @@
+# Stage 1: Build admin-ui
+FROM node:20-alpine AS admin-ui-builder
+WORKDIR /build/admin-ui
+COPY admin-ui/package*.json ./
+RUN npm ci
+COPY admin-ui/ ./
+RUN npm run build
+
+# Stage 2: Build server
+FROM node:20-alpine AS server-builder
+WORKDIR /build
+COPY package*.json ./
+RUN npm ci
+COPY src/ ./src/
+COPY tsconfig.json ./
+RUN npm run build
+
+# Stage 3: Production
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY --from=server-builder /build/lib ./lib
+COPY --from=admin-ui-builder /build/admin-ui/dist ./admin-ui/dist
+COPY bin/ ./bin/
+
+EXPOSE 26192
+CMD ["node", "lib/index.js"]

README.md

@@ -39,7 +39,7 @@ SECURE=false
 TIMEOUT=7000
 ```
 
-See `cache-config.example.yml` for full options and examples. The server supports per-namespace rules, cache expiry, pooling, and query/header-based cache variation.
+The server supports per-namespace rules, cache expiry, pooling, and query/header-based cache variation. See the inline example below and the full config reference in the docs.
 
 ### Example `cache-config.yml`
 
@@ -74,6 +74,40 @@ dummyRest:
       cache: false
 ```
 
+## Allow / Deny URL patterns
+
+Each namespace accepts optional `allow` and `deny` glob pattern lists that control which paths Osham proxies. Requests blocked by these rules receive a `403` response with the header `x-osham-cache: denied`.
+
+**Precedence rules:**
+
+- If `deny` is set and the path matches any pattern → **403 Forbidden** (deny always wins).
+- Else if `allow` is set and the path does **not** match any pattern → **403 Forbidden**.
+- If neither `allow` nor `deny` is present, all paths within the namespace are handled normally (existing behavior unchanged).
+
+**Example:**
+
+```yaml
+myNs:
+  expose: '/api/v1/*'
+  target: 'http://localhost:3000'
+  cache:
+    expires: 10s
+  allow:
+    - '/employees/**'
+    - '/employee/*'
+  deny:
+    - '/employees/private/**'
+```
+
+In this example:
+
+- `/employees/123` → proxied (matches allow)
+- `/employee/5` → proxied (matches allow)
+- `/employees/private/data` → **403** (deny wins, even though it also matches `/employees/**` in allow)
+- `/departments/1` → **403** (not in allow list)
+
+Patterns follow glob syntax (e.g. `*` matches a single path segment, `**` matches any number of segments).
+
 ## Purge cache (administrative)
 
 Osham provides an admin endpoint to invalidate cache by exact key or by pattern. See the detailed guide:
@@ -104,6 +138,30 @@ Scrape this endpoint from your Prometheus instance to track cache efficiency and
 
 - [Metrics](docs/metrics.md)
 
+## Admin UI
+
+Osham now includes a sidecar admin UI under `admin-ui/` for config editing, health/metrics visibility, purge tooling, audit review, config history, rollback, and draft import/export.
+
+### Run the admin UI locally
+
+Start Osham first so the admin API is reachable, then in another shell:
+
+```sh
+cd admin-ui
+npm install
+npm run build
+# or for local development
+npm run dev
+```
+
+By default the Vite dev server proxies `'/__osham/*'` requests to `http://127.0.0.1:26192`. If your Osham server listens elsewhere, override the proxy target:
+
+```sh
+OSHAM_ADMIN_API_TARGET=http://127.0.0.1:3001 npm run dev
+```
+
+The UI stores `x-osham-admin-secret` in `sessionStorage` only and will prompt again if the saved secret is rejected by the admin API.
+
 ## When to use Osham
 
 - Reduce backend load and TTFB for high-read API endpoints
@@ -127,11 +185,26 @@ The diagram below illustrates how Osham handles incoming HTTP GET requests:
 
 ![Osham Architecture](https://raw.githubusercontent.com/ajaysinghj8/osham/master/public/Arch.svg?sanitize=true&raw=true)
 
+## Troubleshooting
+
+Having problems? See the [Troubleshooting guide](docs/troubleshooting.md) for solutions to common issues including:
+
+- Server won't start (missing config, invalid YAML, HTTPS env vars)
+- Cache misses or incorrect TTL behaviour
+- 403 responses from allow/deny rules
+- Purge not working (auth, pattern format)
+- Metrics endpoint returning 404
+- Admin UI auth and CORS issues
+
 ## Contributing
 
-PRs and issues welcome. Run tests with:
+PRs and issues welcome. See the [Contributor Setup guide](docs/contributor-setup.md) for full local setup instructions, test guidance, and PR guidelines.
+
+Quick start:
 
 ```sh
+npm install
+npm run build
 npm test
 ```
 

admin-ui/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Osham Admin</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>