89 lines
3.8 KiB
Markdown
89 lines
3.8 KiB
Markdown
---
|
|
title: Register Custom Routes Safely with Built-in Middlewares
|
|
impact: HIGH
|
|
impactDescription: Protects custom endpoints with auth, avoids /api path collisions, inherits rate limiting
|
|
tags: routing, middleware, extending, requireAuth, apis
|
|
---
|
|
|
|
## Register Custom Routes Safely with Built-in Middlewares
|
|
|
|
PocketBase routing is built on top of `net/http.ServeMux`. Custom routes are registered inside the `OnServe()` hook (Go) or via `routerAdd()` / `routerUse()` (JSVM). **Always** namespace custom routes under `/api/{yourapp}/...` to avoid colliding with built-in endpoints, and attach `apis.RequireAuth()` / `$apis.requireAuth()` (or stricter) to anything that is not meant to be public.
|
|
|
|
**Incorrect (path collision, no auth, raw ResponseWriter):**
|
|
|
|
```go
|
|
// ❌ "/api/records" collides with /api/collections/{name}/records built-in
|
|
se.Router.POST("/api/records", func(e *core.RequestEvent) error {
|
|
// ❌ no auth check - anyone can call this
|
|
// ❌ returns raw text; no content-type
|
|
e.Response.Write([]byte("ok"))
|
|
return nil
|
|
})
|
|
```
|
|
|
|
**Correct (namespaced, authenticated, group-scoped middleware):**
|
|
|
|
```go
|
|
app.OnServe().BindFunc(func(se *core.ServeEvent) error {
|
|
// Group everything under /api/myapp/ and require auth for the entire group
|
|
g := se.Router.Group("/api/myapp")
|
|
g.Bind(apis.RequireAuth()) // authenticated users only
|
|
g.Bind(apis.Gzip()) // compress responses
|
|
g.Bind(apis.BodyLimit(10 << 20)) // per-route override of default 32MB limit
|
|
|
|
g.GET("/profile", func(e *core.RequestEvent) error {
|
|
return e.JSON(http.StatusOK, map[string]any{
|
|
"id": e.Auth.Id,
|
|
"email": e.Auth.GetString("email"),
|
|
})
|
|
})
|
|
|
|
// Superuser-only admin endpoint
|
|
g.POST("/admin/rebuild-index", func(e *core.RequestEvent) error {
|
|
// ... do the work
|
|
return e.JSON(http.StatusOK, map[string]bool{"ok": true})
|
|
}).Bind(apis.RequireSuperuserAuth())
|
|
|
|
// Resource the owner (or a superuser) can access
|
|
g.GET("/users/{id}/private", func(e *core.RequestEvent) error {
|
|
return e.JSON(http.StatusOK, map[string]string{"private": "data"})
|
|
}).Bind(apis.RequireSuperuserOrOwnerAuth("id"))
|
|
|
|
return se.Next()
|
|
})
|
|
```
|
|
|
|
```javascript
|
|
// JSVM
|
|
routerAdd("GET", "/api/myapp/profile", (e) => {
|
|
return e.json(200, {
|
|
id: e.auth.id,
|
|
email: e.auth.getString("email"),
|
|
});
|
|
}, $apis.requireAuth());
|
|
|
|
routerAdd("POST", "/api/myapp/admin/rebuild-index", (e) => {
|
|
return e.json(200, { ok: true });
|
|
}, $apis.requireSuperuserAuth());
|
|
```
|
|
|
|
**Built-in middlewares (Go: `apis.*`, JS: `$apis.*`):**
|
|
|
|
| Middleware | Use |
|
|
|---|---|
|
|
| `RequireGuestOnly()` | Reject authenticated clients (e.g. public signup forms) |
|
|
| `RequireAuth(...collections)` | Require any auth record; optionally restrict to specific auth collections |
|
|
| `RequireSuperuserAuth()` | Alias for `RequireAuth("_superusers")` |
|
|
| `RequireSuperuserOrOwnerAuth("id")` | Allow superusers OR the auth record whose id matches the named path param |
|
|
| `Gzip()` | Gzip-compress the response |
|
|
| `BodyLimit(bytes)` | Override the default 32MB request body cap (0 = no limit) |
|
|
| `SkipSuccessActivityLog()` | Suppress activity log for successful responses |
|
|
|
|
**Path details:**
|
|
- Patterns follow `net/http.ServeMux`: `{name}` = single segment, `{name...}` = catch-all.
|
|
- A trailing `/` acts as a prefix wildcard; use `{$}` to anchor to the exact path only.
|
|
- **Always** prefix custom routes with `/api/{yourapp}/` - do not put them under `/api/` alone, which collides with built-in collection / realtime / settings endpoints.
|
|
- Order: global middlewares → group middlewares → route middlewares → handler. Use negative priorities to run before built-ins if needed.
|
|
|
|
Reference: [Go Routing](https://pocketbase.io/docs/go-routing/) · [JS Routing](https://pocketbase.io/docs/js-routing/)
|