ReviewOS

also looking at this

loghqorg/loghq

Deploy: uniform auth session model (main → production)

#7
Merged glennmichael123 wants to merge main into production
282 files +3028 -64856
docs/basics/routing.mddeleted+0-303
Changes to docs/basics/routing.md
@@ -1,303 +0,0 @@
1---
2title: Routing
3---
4// Points to app/Controllers/ComingSoonController.ts, index method
5route.get('/coming-soon', 'Controllers/ComingSoonController@index')
6
7// Points to app/Controllers/QueryController.ts with various methods
8route.get('/queries/stats', 'Controllers/QueryController@getStats')
9route.get('/queries/recent', 'Controllers/QueryController@getRecentQueries')
10route.get('/queries/slow', 'Controllers/QueryController@getSlowQueries')
11route.get('/queries/:id', 'Controllers/QueryController@getQuery')
12route.post('/queries/prune', 'Controllers/QueryController@pruneQueryLogs')
13
14```
15
16### Action File Structure
17
18When you reference `'Actions/Auth/LoginAction'`, Stacks looks for this file:
19
20```typescript
21
22// app/Actions/Auth/LoginAction.ts
23import type { RequestInstance } from '@stacksjs/types'
24import { Action } from '@stacksjs/actions'
25import { Auth } from '@stacksjs/auth'
26import { response } from '@stacksjs/router'
27import { schema } from '@stacksjs/validation'
28
29export default new Action({
30 name: 'LoginAction',
31 description: 'Login to the application',
32 method: 'POST',
33
34 validations: {
35 email: {
36 rule: schema.string().email(),
37 message: 'Email must be a valid email address.',
38 },
39 password: {
40 rule: schema.string().min(6).max(255),
41 message: 'Password must be between 6 and 255 characters.',
42 },
43 },
44
45 async handle(request: RequestInstance) {
46 const email = request.get('email')
47 const password = request.get('password')
48
49 const result = await Auth.login({ email, password })
50
51 if (result) {
52 return response.json({
53 token: result.token,
54 user: {
55 id: result.user?.id,
56 email: result.user?.email,
57 name: result.user?.name,
58 },
59 })
60 }
61
62 return response.unauthorized('Incorrect email or password')
63 },
64})
65
66```
67
68## Route Groups
69
70Group related routes with shared configuration:
71
72### Prefix Groups
73
74```typescript
75
76// All routes in this group will be prefixed with /auth
77route.group({ prefix: '/auth' }, () => {
78 route.post('/refresh', 'Actions/Auth/RefreshTokenAction')
79 route.get('/tokens', 'Actions/Auth/ListTokensAction')
80 route.post('/token', 'Actions/Auth/CreateTokenAction')
81 route.delete('/tokens/{id}', 'Actions/Auth/RevokeTokenAction')
82})
83
84// Nested prefix groups
85route.group({ prefix: '/api/v1' }, () => {
86 route.group({ prefix: '/users' }, () => {
87 route.get('/', 'Actions/User/IndexAction')
88 route.get('/{id}', 'Actions/User/ShowAction')
89 route.post('/', 'Actions/User/StoreAction')
90 })
91})
92
93```
94
95### Middleware Groups
96
97```typescript
98
99// Apply middleware to all routes in the group
100route.group({ middleware: 'auth' }, () => {
101 route.get('/me', 'Actions/Auth/AuthUserAction')
102 route.post('/logout', 'Actions/Auth/LogoutAction')
103})
104
105// Multiple middleware
106route.group({ middleware: ['auth', 'throttle:60,1'] }, () => {
107 route.get('/dashboard', 'Actions/DashboardAction')
108 route.get('/settings', 'Actions/SettingsAction')
109})
110
111```
112
113### Combined Group Options
114
115```typescript
116
117route.group({ prefix: '/payments', middleware: 'auth' }, () => {
118 route.get('/fetch-customer/{id}', 'Actions/Payment/FetchPaymentCustomerAction')
119 route.get('/transaction-history/{id}', 'Actions/Payment/FetchTransactionHistoryAction')
120 route.post('/create-subscription/{id}', 'Actions/Payment/CreateSubscriptionAction')
121 route.post('/cancel-subscription/{id}', 'Actions/Payment/CancelSubscriptionAction')
122})
123
124```
125
126## Middleware Attachment
127
128### Single Route Middleware
129
130```typescript
131
132// Chain middleware to individual routes
133route.get('/admin', 'Actions/AdminAction').middleware('auth')
134
135// Multiple middleware on a single route
136route.get('/admin/settings', 'Actions/AdminSettingsAction')
137 .middleware('auth')
138 .middleware('abilities:admin')
139
140// Middleware with parameters
141route.post('/api/data', 'Actions/DataAction')
142 .middleware('throttle:100,1')
143 .middleware('auth')
144
145```
146
147### Available Middleware
148
149Stacks comes with several built-in middleware defined in `app/Middleware.ts`:
150
151```typescript
152
153export default {
154 'maintenance': 'Maintenance',
155 'auth': 'Auth',
156 'guest': 'Guest',
157 'api': 'Api',
158 'team': 'Team',
159 'logger': 'Logger',
160 'abilities': 'Abilities',
161 'can': 'Can',
162 'throttle': 'Throttle',
163 'env': 'Env',
164 'env:local': 'EnvLocal',
165 'env:development': 'EnvDevelopment',
166 'env:staging': 'EnvStaging',
167 'env:production': 'EnvProduction',
168} satisfies Middleware
169
170```
171
172For more details, see the [Middleware documentation](/basics/middleware).
173
174## Route File Registry
175
176Stacks uses `app/Routes.ts` to register which route files to load and how to prefix them:
177
178```typescript
179
180// app/Routes.ts
181export default {
182 // Default API routes - loads routes/api.ts at /api/*
183 // (The 'api' key auto-prefixes with /api so user routes line up
184 // with the rpx proxy forward path. See stacksjs/stacks#1835.)
185 'api': 'api',
186
187 // Versioned routes with explicit prefix - loads routes/v1.ts at /v1/*
188 'v1': { path: 'v1', prefix: 'v1' },
189
190 // Admin routes with middleware - loads routes/admin.ts at /admin/*
191 'admin': { path: 'admin', middleware: ['auth'] },
192
193 // No prefix override - loads routes/internal.ts at /* (no prefix)
194 // 'web' is the only key in the route-loader's NO*PREFIX*KEYS list;
195 // for other no-prefix routes, pass an explicit empty string.
196 'internal': { path: 'internal', prefix: '' },
197} satisfies RouteRegistry
198
199```
200
201### Route Definition Types
202
203```typescript
204
205export interface RouteDefinition {
206 /** Route file path (relative to routes/) */
207 path: string
208 /** Optional URL prefix (overrides the key-based prefix) */
209 prefix?: string
210 /** Optional middleware for all routes in file */
211 middleware?: string | string[]
212}
213
214// Simple string format (key becomes prefix)
215'v1': 'api/v1', // Loads routes/api/v1.ts at /v1/*
216
217// Object format with explicit config
218'legacy': { path: 'api/v1', prefix: '/api/v1' },
219
220```
221
222## Special Routes
223
224### Health Check Route
225
226Stacks provides a built-in health check route:
227
228```typescript
229
230// Adds GET /health endpoint
231route.health()
232
233```
234
235This returns a JSON response with service status information.
236
237### Email Route
238
239```typescript
240
241// Adds email preview route (development only)
242route.email('/welcome')
243
244```
245
246## Edge Cases and Advanced Patterns
247
248### Optional Parameters
249
250Currently, Stacks handles optional parameters through separate route definitions:
251
252```typescript
253
254// Two routes for optional parameter
255route.get('/posts', 'Actions/Post/IndexAction')
256route.get('/posts/{category}', 'Actions/Post/IndexAction')
257
258```
259
260### Catch-All Routes
261
262```typescript
263
264// Match any path under /docs
265route.get('/docs/{path}', 'Actions/DocsAction').where('path', '.*')
266
267```
268
269### Route Priority
270
271Routes are matched in the order they are defined. More specific routes should come before catch-all routes:
272
273```typescript
274
275// Specific route first
276route.get('/users/me', 'Actions/User/CurrentUserAction')
277
278// Parameterized route after
279route.get('/users/{id}', 'Actions/User/ShowAction')
280
281// Catch-all route last
282route.get('/users/{path}', 'Actions/User/FallbackAction').where('path', '.*')
283
284```
285
286### Route Naming (Coming Soon)
287
288```typescript
289
290// Future support for named routes
291route.get('/users/{id}', 'Actions/User/ShowAction').name('users.show')
292
293// Generate URL from route name
294const url = route.url('users.show', { id: 123 })
295
296```
297
298## Related Documentation
299
300- [Middleware](/basics/middleware) - Learn about request middleware
301- [Actions](/basics/actions) - Creating action handlers
302- [Controllers](/basics/controllers) - Using controllers
303- [Validation](/packages/validation) - Request validation