@xonovex/skills 0.1.0

package/skills/hono-guidelines/reference/websocket-support.md

@@ -0,0 +1,59 @@
+# websocket-support: WebSocket Server Setup and Route Patterns
+
+**Guideline:** Keep the object reference returned from `createNodeWebSocket()` and call methods on that object rather than destructuring, to maintain proper `this` binding.
+
+**Rationale:** JavaScript methods that rely on `this` context lose their binding when destructured. The `@hono/node-ws` package's `createNodeWebSocket()` returns methods that depend on `this` to access internal state. Keeping the object reference preserves the binding while factory functions like `upgradeWebSocket` can safely be destructured.
+
+**Example:**
+
+```typescript
+import {serve} from "@hono/node-server";
+import {createNodeWebSocket} from "@hono/node-ws";
+import {Hono} from "hono";
+import {createApp} from "./app.js";
+
+const app = createApp();
+
+// ✅ CORRECT - Keep object reference
+const wsHelpers = createNodeWebSocket({app});
+
+const server = serve({
+  fetch: app.fetch,
+  port: 3000,
+});
+
+// Call method on object to maintain binding
+wsHelpers.injectWebSocket(server);
+
+// Destructuring upgradeWebSocket is safe (it's a factory)
+const {upgradeWebSocket} = createNodeWebSocket({app: new Hono()});
+
+export const wsRouter = new Hono();
+
+wsRouter.get(
+  "/chat",
+  upgradeWebSocket(() => ({
+    onOpen(_evt, ws) {
+      console.log("Client connected");
+    },
+    onMessage(event, ws) {
+      const data = JSON.parse(String(event.data)) as {message: string};
+      ws.send(JSON.stringify({echo: data.message}));
+    },
+    onClose(_evt, ws) {
+      console.log("Client disconnected");
+    },
+    onError(evt, ws) {
+      console.error("WebSocket error:", evt);
+    },
+  })),
+);
+```
+
+**Techniques:**
+- Import `createNodeWebSocket` from `@hono/node-ws` and call with `{app}` parameter
+- Keep entire object reference (e.g., `wsHelpers`) for method-based APIs
+- Call methods on the object: `wsHelpers.injectWebSocket(server)`
+- Destructuring factory functions like `upgradeWebSocket` is safe
+- Define WebSocket handlers with onOpen, onMessage, onClose, onError callbacks
+- Use TypeScript types for message data to ensure type safety

package/skills/hono-opinionated-guidelines/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: hono-opinionated-guidelines
+description: >-
+  Trigger on `*.ts` files with Hono imports or `@hono/` packages. Opinionated patterns: inline OpenAPI handlers, router selection, remove unnecessary async, bodyLimit. Keywords: Hono, OpenAPIHono, LinearRouter/RegExpRouter, inline handlers, bodyLimit.
+---
+
+# Hono Opinionated Guidelines
+
+## Requirements
+
+- Hono ≥ 4.0, @hono/node-server, @hono/zod-openapi, TypeScript ≥ 5.8
+
+## Opinionated patterns
+
+- **Async controllers** - Remove unnecessary `async` from synchronous handlers, see [reference/controllers.md](reference/controllers.md)
+- **OpenAPI type inference** - Use inline handlers for type safety, explicit status codes, OpenAPIHono hierarchy, see [reference/openapi-inline-handlers.md](reference/openapi-inline-handlers.md), [reference/openapi-explicit-status-codes.md](reference/openapi-explicit-status-codes.md), [reference/openapi-router-hierarchy.md](reference/openapi-router-hierarchy.md)
+- **OpenAPI documentation** - Use `app.doc()` for automatic spec generation, see [reference/openapi-spec-generation.md](reference/openapi-spec-generation.md)
+- **Router selection** - LinearRouter for serverless, RegExpRouter for high-throughput, see [reference/router-selection.md](reference/router-selection.md)
+- **Request limits** - Use `bodyLimit` middleware to prevent DoS, see [reference/body-limit.md](reference/body-limit.md)
+
+## Example
+
+```typescript
+import {OpenAPIHono} from "@hono/zod-openapi";
+import {bodyLimit} from "hono/body-limit";
+import {secureHeaders} from "hono/secure-headers";
+
+export function createApp() {
+  const app = new OpenAPIHono();
+  app.use("*", secureHeaders());
+  app.use("*", bodyLimit({maxSize: 100 * 1024}));
+  app.route("/api/v1", v1Router);
+  app.doc("/openapi.json", {
+    openapi: "3.1.0",
+    info: {title: "API", version: "1.0.0"},
+  });
+  return app;
+}
+```
+
+## Progressive disclosure
+
+- Read [reference/controllers.md](reference/controllers.md) - When seeing unnecessary async functions
+- Read [reference/openapi-inline-handlers.md](reference/openapi-inline-handlers.md) - When OpenAPI loses type inference
+- Read [reference/openapi-explicit-status-codes.md](reference/openapi-explicit-status-codes.md) - When defining OpenAPI response schemas
+- Read [reference/openapi-router-hierarchy.md](reference/openapi-router-hierarchy.md) - When composing multiple routers
+- Read [reference/openapi-spec-generation.md](reference/openapi-spec-generation.md) - When generating OpenAPI documentation
+- Read [reference/router-selection.md](reference/router-selection.md) - When optimizing for serverless/edge or high-throughput
+- Read [reference/body-limit.md](reference/body-limit.md) - When preventing oversized request payloads

package/skills/hono-opinionated-guidelines/reference/application-structure.md

@@ -0,0 +1,53 @@
+# application-structure: Application Factory and Router Organization
+
+**Guideline:** Use factory functions to create Hono applications instead of exporting instances, and organize routes into separate router files by domain.
+
+**Rationale:** Factory functions enable testability by creating fresh instances per test, support dependency injection, and improve isolation. Domain-based router organization provides clear separation of concerns and reduces merge conflicts in team environments.
+
+**Example:**
+
+```typescript
+// src/app.ts - Main application factory
+import {Hono} from "hono";
+import {cors} from "hono/cors";
+import {logger} from "hono/logger";
+import {v1Router} from "./routes/v1/index.js";
+import {v2Router} from "./routes/v2/index.js";
+
+export function createApp() {
+  const app = new Hono();
+
+  // Global middleware
+  app.use("*", logger());
+  app.use("*", cors());
+
+  // Mount routers by version
+  app.route("/api/v1", v1Router);
+  app.route("/api/v2", v2Router);
+
+  return app;
+}
+
+// src/routes/v1/users.ts - Domain router
+import {Hono} from "hono";
+import {zValidator} from "@hono/zod-validator";
+import * as controller from "../../controllers/users.controller.js";
+import {CreateUserSchema} from "../../schemas/users.js";
+
+export const usersRouter = new Hono();
+
+usersRouter.post(
+  "/",
+  zValidator("json", CreateUserSchema),
+  controller.createUser,
+);
+```
+
+**Techniques:**
+- Create `createApp()` factory function instead of exporting instances
+- Configure global middleware inside the factory
+- Mount domain routers using `app.route()`
+- Organize routers in separate files by domain (users, items, etc.)
+- Import controllers from dedicated controller files
+- Keep route definitions focused on routing logic only
+- Export factory functions for testability

package/skills/hono-opinionated-guidelines/reference/body-limit.md

@@ -0,0 +1,57 @@
+# body-limit: Preventing Large Payload Attacks
+
+**Guideline:** Use Body Limit middleware to prevent DoS attacks from oversized request payloads, configuring appropriate limits per endpoint based on expected data.
+
+**Rationale:** Large request bodies can exhaust server memory, cause denial of service, and overwhelm downstream services. Body Limit middleware rejects requests before fully reading them, uses stream reading without Content-Length requirements, and returns 413 Payload Too Large status while remaining configurable per route.
+
+**Example:**
+
+```typescript
+import {bodyLimit} from "hono/body-limit";
+
+// Global limit for most endpoints
+app.use(
+  "*",
+  bodyLimit({
+    maxSize: 100 * 1024, // 100KB default
+    onError: (c) => {
+      return c.json(
+        {
+          type: "about:blank#payload-too-large",
+          title: "Payload Too Large",
+          status: 413,
+          detail: "Request body exceeds 100KB limit",
+        },
+        413,
+      );
+    },
+  }),
+);
+
+// Higher limit for file uploads
+app.post(
+  "/upload",
+  bodyLimit({
+    maxSize: 10 * 1024 * 1024, // 10MB for uploads
+  }),
+  async (c) => {
+    const body = await c.req.parseBody();
+    // Handle file upload
+  },
+);
+
+// Stricter limit for JSON APIs
+app.use(
+  "/api/*",
+  bodyLimit({
+    maxSize: 50 * 1024, // 50KB for JSON
+  }),
+);
+```
+
+**Techniques:**
+- Import `bodyLimit` from `hono/body-limit` and set appropriate `maxSize` in bytes
+- Apply globally with app.use() or per-route for flexibility
+- Configure different limits for different endpoints (100KB default, 10MB for uploads)
+- Provide custom `onError` handler for formatted error responses
+- Consider internal vs public services when setting limits

package/skills/hono-opinionated-guidelines/reference/context-storage.md

@@ -0,0 +1,46 @@
+# context-storage: Access Context Globally with AsyncLocalStorage
+
+**Guideline:** Use `contextStorage()` middleware with `getContext()` to access Hono Context outside route handlers, enabling cleaner service layer code without parameter drilling.
+
+**Rationale:** AsyncLocalStorage provides global access to the current request context without parameter drilling through the call stack, enabling clean separation between routing and business logic while automatically cleaning up context after requests.
+
+**Example:**
+
+```typescript
+import {Hono} from "hono";
+import {contextStorage, getContext} from "hono/context-storage";
+
+const app = new Hono();
+
+// Enable context storage early
+app.use(contextStorage());
+
+// Set request metadata
+app.use("*", async (c, next) => {
+  c.set("requestId", crypto.randomUUID());
+  c.set("tenantId", c.req.header("X-Tenant-ID"));
+  await next();
+});
+
+app.get("/items", (c) => {
+  const items = itemsService.list(); // No context passed
+  return c.json(items);
+});
+
+// In service layer (separate file)
+export function list() {
+  const c = getContext();
+  const tenantId = c.get("tenantId");
+  const requestId = c.get("requestId");
+
+  logger.info(`[${requestId}] Listing items for tenant ${tenantId}`);
+  return db.items.findMany({where: {tenantId}});
+}
+```
+
+**Techniques:**
+- Import `contextStorage` and `getContext` from `hono/context-storage`
+- Apply `contextStorage()` middleware early in middleware chain
+- Call `getContext()` anywhere during request handling to access context
+- For Cloudflare Workers enable `nodejs_compat` flag
+- Use sparingly as explicit parameters are more testable

package/skills/hono-opinionated-guidelines/reference/controllers.md

@@ -0,0 +1,38 @@
+# controllers: Remove Unnecessary Async from Synchronous Controllers
+
+**Guideline:** Remove the `async` keyword from controller functions that don't use `await`, as unnecessary async adds overhead without providing benefits.
+
+**Rationale:** Marking a function `async` without awaiting anything creates unnecessary Promise wrapping overhead, adds microtask queue delays, and misleads developers about async operations. Synchronous controllers are faster, clearer in intent, and produce simpler stack traces.
+
+**Example:**
+
+```typescript
+import type {Context} from "hono";
+
+// ✅ CORRECT - No async needed
+export function getUser(c: Context) {
+  const {id} = (c.req.valid as (target: string) => {id: string})("param");
+  const user = userService.getById(id); // Synchronous call
+  return c.json(user);
+}
+
+// ✅ CORRECT - Async needed for await
+export async function createUser(c: Context) {
+  const data = (c.req.valid as (target: string) => CreateUser)("json");
+  const user = await userService.create(data); // Awaiting async operation
+  return c.json(user, 201);
+}
+
+// ✅ CORRECT - No async, just returns response
+export function listUsers(c: Context) {
+  const users = userService.list();
+  return c.json(users);
+}
+```
+
+**Techniques:**
+- Review controller function body for `await` keyword usage
+- Remove `async` keyword if no `await` exists in function
+- Ensure return statements work with or without async (c.json() compatible)
+- Keep `async` only when awaiting DB queries, external APIs, or other async operations
+- Check for performance improvements after removing unnecessary async

package/skills/hono-opinionated-guidelines/reference/cookie-handling.md

@@ -0,0 +1,63 @@
+# cookie-handling: Secure Cookie Configuration and Signed Cookies
+
+**Guideline:** Set secure cookie options explicitly, use signed cookies for sensitive data, and follow browser-enforced prefix requirements for additional security.
+
+**Rationale:** Cookies require careful configuration to ensure HTTPS-only transmission, prevent JavaScript access, defend against CSRF, and verify integrity. Cookie prefixes enforce additional security guarantees, while signed cookies prevent tampering and provide strong integrity verification for sensitive client-side state.
+
+**Example:**
+
+```typescript
+import {
+  getCookie,
+  getSignedCookie,
+  setCookie,
+  setSignedCookie,
+} from "hono/cookie";
+
+// Standard secure cookie
+app.post("/login", (c) => {
+  setCookie(c, "session", sessionId, {
+    secure: true,
+    httpOnly: true,
+    sameSite: "Strict",
+    maxAge: 86400, // 1 day
+    path: "/",
+  });
+  return c.json({success: true});
+});
+
+// Signed cookie for integrity (async)
+app.post("/preferences", async (c) => {
+  await setSignedCookie(c, "prefs", JSON.stringify(prefs), "secret-key", {
+    secure: true,
+    httpOnly: true,
+    sameSite: "Lax",
+  });
+  return c.json({saved: true});
+});
+
+// Verify signed cookie
+app.get("/preferences", async (c) => {
+  const prefs = await getSignedCookie(c, "secret-key", "prefs");
+  if (prefs === false) {
+    return c.json({error: "Invalid signature"}, 400);
+  }
+  return c.json(JSON.parse(prefs ?? "{}"));
+});
+
+// Host-prefixed cookie (strictest)
+setCookie(c, "__Host-session", token, {
+  secure: true,
+  path: "/",
+  // domain must NOT be set for __Host- prefix
+});
+```
+
+**Techniques:**
+- Import cookie helpers from `hono/cookie` (setCookie, getCookie, setSignedCookie, getSignedCookie)
+- Always set `secure: true` and `httpOnly: true` for sensitive cookies
+- Use `sameSite: 'Strict'` for maximum CSRF protection or `'Lax'` for better compatibility
+- Use `setSignedCookie` (async) for cookies requiring integrity verification
+- Verify signed cookies with `getSignedCookie` and check for false value on tampering
+- Use `__Host-` prefix for strictest cookie restrictions (requires `secure: true` and `path: '/'`)
+- Keep `maxAge` under 400 days to respect browser limits

package/skills/hono-opinionated-guidelines/reference/error-handling.md

@@ -0,0 +1,69 @@
+# error-handling: RFC 7807 Problem Details for Consistent Error Responses
+
+**Guideline:** Use RFC 7807 Problem Details format for all error responses to provide consistent, structured, machine-readable error information across your API.
+
+**Rationale:** RFC 7807 provides a standard structure recognized across HTTP APIs, enabling clients to parse errors consistently with machine-readable field-level validation details and request context. Built-in extensibility and separation between human and machine-readable fields improves debugging and error handling.
+
+**Example:**
+
+```typescript
+import type {Context} from "hono";
+import type {z} from "zod";
+
+export interface ProblemDetails {
+  type: string;
+  title: string;
+  status: number;
+  detail?: string;
+  instance?: string;
+  issues?: {
+    path: string[];
+    message: string;
+    code?: string;
+  }[];
+}
+
+export function badRequest(c: Context, error: z.ZodError): Response {
+  const problem: ProblemDetails = {
+    type: "about:blank#bad-request",
+    title: "Bad Request",
+    status: 400,
+    detail: "Request validation failed",
+    instance: c.req.path,
+    issues: error.issues.map((issue) => ({
+      path: issue.path.map(String),
+      message: issue.message,
+      code: issue.code,
+    })),
+  };
+
+  return new Response(JSON.stringify(problem), {
+    status: 400,
+    headers: {"Content-Type": "application/json"},
+  });
+}
+
+export function notFound(c: Context, detail: string): Response {
+  const problem: ProblemDetails = {
+    type: "about:blank#not-found",
+    title: "Not Found",
+    status: 404,
+    detail,
+    instance: c.req.path,
+  };
+
+  return new Response(JSON.stringify(problem), {
+    status: 404,
+    headers: {"Content-Type": "application/json"},
+  });
+}
+```
+
+**Techniques:**
+- Define `ProblemDetails` TypeScript interface matching RFC 7807 spec
+- Include required fields: type, title, status
+- Include optional fields: detail, instance, custom extensions
+- For validation errors add `issues` array with field-level details
+- Create helper functions for common error types (badRequest, notFound, etc.)
+- Return proper HTTP status codes matching the status field
+- Set `Content-Type: application/json` header

package/skills/hono-opinionated-guidelines/reference/middleware-combine.md

@@ -0,0 +1,47 @@
+# middleware-combine: Composing Middleware with some, every, except
+
+**Guideline:** Use the `combine` module (`some`, `every`, `except`) to compose complex middleware logic for conditional execution and access control.
+
+**Rationale:** The combine module provides declarative composition of complex requirements: `some()` implements OR logic for alternative auth methods, `every()` implements AND logic for layered checks, and `except()` skips middleware for specific paths, enabling cleaner code than nested conditionals.
+
+**Example:**
+
+```typescript
+import {basicAuth} from "hono/basic-auth";
+import {bearerAuth} from "hono/bearer-auth";
+import {every, except, some} from "hono/combine";
+
+// Accept either basic auth OR bearer token
+app.use(
+  "/api/*",
+  some(
+    basicAuth({verifyUser: verifyBasicAuth}),
+    bearerAuth({verifyToken: verifyBearerToken}),
+  ),
+);
+
+// Must be authenticated AND have admin role
+app.use(
+  "/admin/*",
+  every(bearerAuth({verifyToken: verifyToken}), async (c, next) => {
+    const user = c.get("user");
+    if (user.role !== "admin") {
+      return c.json({error: "Forbidden"}, 403);
+    }
+    await next();
+  }),
+);
+
+// Apply rate limiting to all routes EXCEPT health checks
+app.use("*", except("/health", rateLimiter({max: 100, window: 60})));
+
+// Multiple path exclusions
+app.use("*", except(["/health", "/metrics", "/ready"], authMiddleware()));
+```
+
+**Techniques:**
+- Import `some`, `every`, `except` from `hono/combine`
+- Use `some()` for alternative auth methods (OAuth OR API key)
+- Use `every()` for layered requirements (authenticated AND has role)
+- Use `except()` for path-based middleware exclusions
+- Combine module handlers with other Hono middleware seamlessly

package/skills/hono-opinionated-guidelines/reference/middleware-patterns.md

@@ -0,0 +1,58 @@
+# middleware-patterns: CORS Configuration and Custom Middleware
+
+**Guideline:** Configure CORS differently for development and production, and use middleware factory functions to ensure proper `this` binding and parameterization.
+
+**Rationale:** Environment-specific CORS balances development convenience with production security. Middleware factories ensure correct context binding in async operations, enable parameterization, and provide consistent patterns across applications through proper closure over configuration values.
+
+**Example:**
+
+```typescript
+import type {Context, Next} from "hono";
+import {cors} from "hono/cors";
+
+// Environment-specific CORS
+const isDevelopment = process.env.NODE_ENV === "development";
+
+if (isDevelopment) {
+  // Development: Permissive
+  app.use(
+    "*",
+    cors({
+      origin: "*",
+      allowMethods: ["GET", "POST", "PUT", "DELETE"],
+      maxAge: 86_400, // 24 hours
+    }),
+  );
+} else {
+  // Production: Restrictive
+  app.use(
+    "*",
+    cors({
+      origin: ["https://app.example.com"],
+      allowMethods: ["GET", "POST", "PUT", "DELETE"],
+      credentials: true,
+      maxAge: 600, // 10 minutes
+    }),
+  );
+}
+
+// Custom middleware factory with proper binding
+function requestId() {
+  return async (c: Context, next: Next) => {
+    const id = crypto.randomUUID();
+    c.set("requestId", id);
+    c.header("X-Request-ID", id);
+    await next();
+  };
+}
+
+app.use("*", requestId());
+```
+
+**Techniques:**
+- Import CORS from `hono/cors` and configure based on environment
+- For development use `origin: "*"` for permissive access
+- For production specify allowed origins explicitly
+- Create middleware factory function that returns `async (c, next) => {...}`
+- Call factory function when registering: `app.use("*", requestId())`
+- Never destructure methods from helpers that rely on `this` binding

package/skills/hono-opinionated-guidelines/reference/openapi-explicit-status-codes.md

@@ -0,0 +1,61 @@
+# openapi-explicit-status-codes: Always Provide Explicit Status Codes in Responses
+
+**Guideline:** Always provide explicit status codes in all `c.json()` calls within OpenAPI routes, as discriminated unions require them for proper TypeScript type narrowing.
+
+**Rationale:** OpenAPI routes define multiple possible response types, each with a specific status code. TypeScript uses discriminated unions to represent these possibilities. Without explicit status codes, TypeScript cannot narrow the response type at compile time, causing type inference to break and losing type safety guarantees.
+
+**Example:**
+
+```typescript
+import {createRoute, z} from "@hono/zod-openapi";
+
+const getItemRoute = createRoute({
+  method: "get",
+  path: "/items/{id}",
+  responses: {
+    200: {
+      content: {"application/json": {schema: ItemSchema}},
+      description: "Item found",
+    },
+    404: {
+      content: {"application/json": {schema: ProblemDetailsSchema}},
+      description: "Item not found",
+    },
+  },
+});
+
+// ✅ CORRECT - Explicit status codes
+itemsRouter.openapi(getItemRoute, (c) => {
+  const {id} = c.req.valid("param");
+  const item = itemsService.findById(id);
+
+  if (!item) {
+    return c.json(
+      {
+        type: "about:blank#not-found",
+        title: "Not Found",
+        status: 404,
+        detail: "Item not found",
+      },
+      404,
+    ); // Explicit status code
+  }
+
+  return c.json(item, 200); // Explicit status code
+});
+
+// ✅ CORRECT - Explicit 201 for creation
+itemsRouter.openapi(createItemRoute, (c) => {
+  const data = c.req.valid("json");
+  const item = itemsService.create(data);
+  return c.json(item, 201); // Explicit 201 for created resource
+});
+```
+
+**Techniques:**
+- Review all `c.json()` calls in OpenAPI handlers and add status code parameter
+- Use 200 for success (OK) and 201 for creation (Created)
+- Use 400 (Bad Request), 404 (Not Found), 500 (Server Error) for error cases
+- Match status codes to those defined in route's `responses` object
+- For Problem Details errors, include status in both response object and HTTP status
+- Never rely on implicit default status codes in OpenAPI routes

package/skills/hono-opinionated-guidelines/reference/openapi-inline-handlers.md

@@ -0,0 +1,56 @@
+# openapi-inline-handlers: Use Inline Handlers for OpenAPI Routes
+
+**Guideline:** Implement handler logic inline within OpenAPI route definitions instead of separate controller functions to enable proper TypeScript type inference from route schemas.
+
+**Rationale:** Hono's OpenAPI integration uses TypeScript type inference to match route schemas with handlers. This only works with inline handlers because TypeScript cannot infer types across function boundaries, and separate controllers return generic `Response` types instead of being automatically typed by route definitions.
+
+**Example:**
+
+```typescript
+import {createRoute, OpenAPIHono, z} from "@hono/zod-openapi";
+
+// Define route with schemas
+const listItemsRoute = createRoute({
+  method: "get",
+  path: "/items",
+  request: {
+    query: z.object({
+      page: z.coerce.number().default(1),
+      limit: z.coerce.number().default(10),
+    }),
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            items: z.array(ItemSchema),
+            pagination: z.object({
+              page: z.number(),
+              limit: z.number(),
+              total: z.number(),
+            }),
+          }),
+        },
+      },
+      description: "List of items",
+    },
+  },
+});
+
+// ✅ CORRECT - Inline handler with type inference
+itemsRouter.openapi(listItemsRoute, (c) => {
+  // Types automatically inferred from route definition
+  const {page, limit} = c.req.valid("query");
+  const {items, total} = itemsService.listItems(page, limit);
+  return c.json({items, pagination: {page, limit, total}}, 200);
+});
+```
+
+**Techniques:**
+- Define route using `createRoute()` with full request and response schemas
+- Register route with `router.openapi(route, (c) => {...})` with inline handler
+- Access validated data via `c.req.valid()` to get automatically typed request data
+- Return responses with `c.json(data, statusCode)` and explicit status codes
+- Keep route handler focused on request/response mapping
+- Extract complex business logic to service functions called from handler