fix docs

Author: muhammad-fiaz

README.md

@@ -27,7 +27,7 @@
 
 ---
 
-> Note: This Project is in active development. Breaking changes may occur in minor releases.
+> Note: This Project is in active development. Currently, Breaking changes may occur in every commit. Use at your own risk.
 
 ## ✨ Features
 

docs/guide/caching.md

@@ -0,0 +1,18 @@
+# Caching
+
+api.zig provides in-memory caching primitives geared for HTTP responses and application data.
+
+## Features
+
+- LRU eviction
+- TTL expiration
+- Response caching middleware with ETag support
+
+## Example
+
+```zig
+var cache = ResponseCache.init(allocator, .{ .max_size = 1000 });
+app.addMiddleware(cache.cacheMiddleware(&cache));
+```
+
+See `src/cache.zig` for cache configuration, invalidation, and helper utilities.

docs/guide/deployment.md

@@ -0,0 +1,33 @@
+# Deployment
+
+Guidance for deploying `api.zig` applications in production.
+
+## Recommendations
+
+- Run behind a reverse proxy (nginx, Caddy) or a load-balancer for TLS termination.
+- Use systemd or container orchestrators (Docker, Kubernetes) for process supervision.
+- Configure environment variables for runtime config (port, address, feature flags).
+
+## Example systemd unit
+
+```
+[Unit]
+Description=api.zig service
+After=network.target
+
+[Service]
+Type=simple
+User=www-data
+ExecStart=/opt/myapp/bin/myapp
+Restart=on-failure
+
+[Install]
+WantedBy=multi-user.target
+```
+
+## Containers
+
+- Build small images (static binary will help) and use health and readiness probes in orchestrators.
+- For multi-replica setups, use an external session store (Redis) and centralized logs/metrics.
+
+Refer to the docs above (Metrics, Health Checks, Caching) for production concerns.

docs/guide/health-checks.md

@@ -0,0 +1,18 @@
+# Health Checks
+
+api.zig supports health checks for production readiness and liveness probes.
+
+## Built-in Checks
+
+- Aggregated health status (ok/warning/fail)
+- Custom checks (database, caches, external services)
+
+Example:
+
+```zig
+var hc = try metrics.HealthChecks.init(allocator);
+hc.addCheck("postgres", checkPostgresFn);
+app.get("/health", (ctx) => Response.json(hc.statusJson()));
+```
+
+See `src/metrics.zig` for health check utilities and JSON output format.

docs/guide/metrics.md

@@ -0,0 +1,18 @@
+# Metrics
+
+Collect metrics and export Prometheus-compatible metrics with the built-in registry.
+
+## Exporting Metrics
+
+- Use `metrics.Registry` to register counters, gauges and histograms.
+- Expose metrics endpoint and call `registry.scrape()` to generate Prometheus text.
+
+Example:
+
+```zig
+var registry = try metrics.Registry.init(allocator);
+registry.registerCounter("requests_total", "Total requests");
+app.get("/metrics", (ctx) => Response.text(registry.scrape()))
+```
+
+See `src/metrics.zig` for implementation details and health check integrations.

docs/guide/sessions.md

@@ -0,0 +1,22 @@
+# Sessions
+
+api.zig provides a secure session management system with pluggable backends (in-memory, Redis, etc.).
+
+## Basics
+
+- Create a `Session.Manager` and configure cookie name, TTL, secure flag, and storage backend.
+- Use `sessionMiddleware(manager)` to enable automatic session loading/saving for requests.
+
+## Example
+
+```zig
+const manager = try session.Manager.init(allocator, manager_config);
+app.addMiddleware(sessionMiddleware(&manager));
+```
+
+## Tips
+
+- Use secure cookies (`Secure=true`) in production and set `SameSite` appropriately.
+- Use server-side stores (e.g., Redis) for multi-process deployments.
+
+See the `src/session.zig` API docs for configuration options and storage interfaces.

docs/guide/websocket.md

@@ -0,0 +1,24 @@
+# WebSocket
+
+api.zig includes RFC-6455 WebSocket support with an extensible connection hub and handlers for real-time apps.
+
+## Quick Start
+
+- Create a `WebSocket.Hub` and register event handlers.
+- Use `app.upgradeToWebSocket(...)` (or the provided helper) in a route to accept WebSocket connections.
+
+Example:
+
+```zig
+const hub = try websocket.Hub.init(allocator);
+app.get("/ws", (ctx) => websocket.accept(ctx, &hub));
+```
+
+## Features
+
+- Ping/Pong heartbeats
+- Reconnection-friendly message framing
+- Room/channel broadcasting
+- GraphQL subscription integration (see GraphQL docs)
+
+See `src/websocket.zig` for low-level details and available helpers.

examples/graphql.zig

@@ -0,0 +1,6 @@
+const std = @import("std");
+const server = @import("graphql_server.zig");
+
+pub fn main() !void {
+    try server.main();
+}

src/app.zig

@@ -384,15 +384,21 @@ pub const App = struct {
 
         // GraphQL endpoint handler with introspection support
         const GraphQLHandler = struct {
+            var logger: ?*Logger = null;
             var cached_introspection: []const u8 = "";
 
+            fn setLogger(l: *Logger) void {
+                logger = l;
+            }
+
             fn setCachedIntrospection(data: []const u8) void {
                 cached_introspection = data;
             }
 
             fn handle(ctx: *Context) Response {
                 // Handle CORS preflight
                 if (ctx.method() == .OPTIONS) {
+                    if (logger) |lg| lg.debug("[GraphQL] OPTIONS preflight received", null) catch {} else std.debug.print("[GraphQL] OPTIONS preflight received\n", .{});
                     return Response.init()
                         .setStatus(.no_content)
                         .setHeader("Access-Control-Allow-Origin", "*")
@@ -403,29 +409,37 @@ pub const App = struct {
 
                 // For POST requests, check if it's an introspection query
                 const body = ctx.body();
-                if (body.len > 0 and std.mem.indexOf(u8, body, "__schema") != null) {
-                    return Response.jsonRaw(cached_introspection)
-                        .setHeader("Access-Control-Allow-Origin", "*");
+                if (body.len > 0) {
+                    const snippet = if (body.len > 512) body[0..512] else body;
+                    if (logger) |lg| lg.debugf("[GraphQL] POST body (first 512 bytes): {s}", .{snippet}, null) catch {} else std.debug.print("[GraphQL] POST body (first 512 bytes): {s}\n", .{snippet});
+                    if (std.mem.indexOf(u8, body, "__schema") != null) {
+                        if (logger) |lg| lg.debug("[GraphQL] Detected introspection query in POST body", null) catch {} else std.debug.print("[GraphQL] Detected introspection query in POST body\n", .{});
+                        return Response.jsonRaw(cached_introspection)
+                            .setHeader("Access-Control-Allow-Origin", "*");
+                    }
                 }
 
                 // For GET requests with introspection
                 if (ctx.method() == .GET) {
                     if (ctx.query("query")) |query| {
                         if (std.mem.indexOf(u8, query, "__schema") != null) {
+                            if (logger) |lg| lg.debug("[GraphQL] Detected introspection query in GET", null) catch {} else std.debug.print("[GraphQL] Detected introspection query in GET\n", .{});
                             return Response.jsonRaw(cached_introspection)
                                 .setHeader("Access-Control-Allow-Origin", "*");
                         }
                     }
                 }
 
                 // Default response for non-introspection queries
+                if (logger) |lg| lg.debug("[GraphQL] Non-introspection request received", null) catch {} else std.debug.print("[GraphQL] Non-introspection request received\n", .{});
                 return Response.json(.{ .data = null, .message = "Query execution not yet implemented" })
                     .setHeader("Access-Control-Allow-Origin", "*");
             }
         };
 
         // Set the cached introspection data
         GraphQLHandler.setCachedIntrospection(introspection_json);
+        GraphQLHandler.setLogger(self.logger);
 
         const PlaygroundHandler = struct {
             fn handle(ctx: *Context) Response {