convex-runtime

<overview> Implement Convex runtime features: HTTP actions, file storage, search (full text + vector), and scheduling. </overview>

<reference>

• HTTP actions: https://docs.convex.dev/functions/http-actions
• File storage: https://docs.convex.dev/file-storage
• Uploading files: https://docs.convex.dev/file-storage/upload-files
• Serving files: https://docs.convex.dev/file-storage/serve-files
• File metadata: https://docs.convex.dev/file-storage/file-metadata
• Full text search: https://docs.convex.dev/search/text-search
• Vector search: https://docs.convex.dev/search/vector-search
• Scheduling: https://docs.convex.dev/scheduling
• Scheduled functions: https://docs.convex.dev/scheduling/scheduled-functions
• Cron jobs: https://docs.convex.dev/scheduling/cron-jobs

</reference>

<context name="Runtime Concepts">

• Full text search: searchIndex with searchField and optional filterFields; relevance-ordered; prefix matching on final term; fuzzy matches are deprecated; limits 16 terms, 8 filters, 1024 scanned.
• Vector search: vectorIndex with vectorField and dimensions (2-4096); vector field is v.array(v.float64()); actions-only; limits 256 results, 64 filters, 4 vector indexes per table.
• Scheduling: scheduled functions are durable and stored in DB; cron jobs run on fixed schedules; auth not propagated, You MUST pass identity explicitly.
• File storage: upload URLs for large files; HTTP action uploads limited to 20MB; metadata in _storage.

</context>

<rules>

Runtime Operations

• HTTP actions: define handlers with httpAction, register in convex/http.ts via httpRouter (default export REQUIRED).
• HTTP Syntax:

``ts http.route({ path: "/api/echo", // Exact path method: "POST", handler: httpAction(async (ctx, req) => { const body = await req.bytes(); return new Response(body, { status: 200 }); }), }); ``

• HTTP actions MUST be exposed at https://<deployment>.convex.site.
• Upload URL flow: generate URL mutation → client POST → store storageId; URLs expire after 1 hour.
• HTTP upload flow: ctx.storage.store(blob) then mutation. Uploads via HTTP actions are limited to 20MB.
• Serving files: ctx.storage.getUrl(storageId) in queries/mutations; returns signed URL or null.
• File metadata: ctx.db.system.get("storage", id) or query("storage"); storage.getMetadata() is deprecated.
• Scheduling: ctx.scheduler.runAfter/runAt; cron jobs in convex/crons.ts using cronJobs().
• Cron Scheduling: You MUST use crons.interval or crons.cron. You MUST NOT use deprecated helpers like crons.hourly, crons.daily, or crons.weekly.
• Cron internal calls: If a cron calls an internal function, You MUST import the internal object from _generated/api to reference it, even if defined in the same file.

Core Rules

• HTTP actions MUST be routed only via convex/http.ts default export.
• HTTP actions MUST parse Request manually as they do not support validators.
• Search Example:

``ts const messages = await ctx.db.query("messages") .withSearchIndex("search_body", (q) => q.search("body", "hello hi").eq("channel", "#general") ).take(10); ``

• Vector search MUST be actions-only; results are non-reactive.
• Search behavior: full text search is relevance-ordered and uses prefix matching on the final term; fuzzy matches are deprecated.
• You SHOULD prefer search/vector filters in index definitions and query filters.
• Scheduled functions MUST remain backward compatible with args.

</rules>