odac 1.4.15 → 1.4.17

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 ### 🛠️ Fixes & Improvements
 
+- repair broken redis pub/sub delivery and align unsubscribe() across drivers
+- send() no longer JSON-serializes Buffer/TypedArray into TEXT frames
+- **test:** close WebSocketClient instances left open after each test
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
+### ✨ What's New
+
+- add multipart file upload support with validation
+
+### 🛠️ Fixes & Improvements
+
+- **auth:** enhance token validation and anomaly detection mechanisms
+- patch file descriptor leak, polling anti-pattern, mimetype guard and duplicate move check
+- **test:** improve temp file cleanup logic in multipart tests for reliability
+- update cache directory handling to use global.__dir for consistency
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
+### 🛠️ Fixes & Improvements
+
 - **docs:** update references from 'odac' to 'Odac' for consistency
 - **form:** improve form submission handler ownership to prevent duplicate submissions
 - **form:** prevent multiple submit handlers on re-bound forms

package/client/odac.js

@@ -479,6 +479,43 @@ if (typeof window !== 'undefined') {
             errorSpan.textContent = ''
           }
 
+          if (input.type === 'file') {
+            const files = input.files
+            if (input.hasAttribute('required') && files.length === 0) {
+              showError(input, 'required')
+              break
+            }
+            const maxFiles = parseInt(input.getAttribute('data-maxfiles'))
+            if (maxFiles && files.length > maxFiles) {
+              showError(input, 'maxfiles')
+              break
+            }
+            const maxSize = parseInt(input.getAttribute('data-maxsize'))
+            if (maxSize && [...files].some(f => f.size > maxSize)) {
+              showError(input, 'maxsize')
+              break
+            }
+            const minSize = parseInt(input.getAttribute('data-minsize'))
+            if (minSize && [...files].some(f => f.size < minSize)) {
+              showError(input, 'minsize')
+              break
+            }
+            const accept = input.getAttribute('accept')
+            if (accept && files.length) {
+              const tokens = accept.split(',').map(t => t.trim().toLowerCase())
+              const ok = [...files].every(f =>
+                tokens.some(t =>
+                  t.startsWith('.') ? f.name.toLowerCase().endsWith(t) : t.endsWith('/*') ? f.type.startsWith(t.slice(0, -1)) : f.type === t
+                )
+              )
+              if (!ok) {
+                showError(input, 'accept')
+                break
+              }
+            }
+            continue
+          }
+
           if (input.hasAttribute('required')) {
             const isEmpty = input.type === 'checkbox' || input.type === 'radio' ? !input.checked : !input.value.trim()
             if (isEmpty) {
@@ -523,7 +560,7 @@ if (typeof window !== 'undefined') {
         let datastring, cache, contentType, processData
         if (formElement.querySelector('input[type=file]')) {
           datastring = new FormData(formElement)
-          datastring.append('token', this.token())
+          datastring.append('_token', this.token())
           cache = false
           contentType = false
           processData = false

package/docs/ai/skills/backend/forms.md

@@ -101,12 +101,63 @@ module.exports = class Contact {
 ```
 
 ## Field-Level Variants
-- **Input types**: `text`, `email`, `password`, `number`, `url`, `textarea`, `checkbox`.
-- **Validation mapping**: `required|minlen|maxlen|min|max|alpha|alphanumeric|numeric|email|url|accepted`.
-- **Pass-through attrs**: Unrecognized `<odac:input ...>` attributes are preserved into generated HTML input/textarea.
+- **Input types**: `text`, `email`, `password`, `number`, `url`, `textarea`, `checkbox`, `file`.
+- **Validation mapping**: `required|minlen|maxlen|min|max|alpha|alphanumeric|numeric|email|url|accepted|maxsize|minsize|mimetype|ext|maxfiles`.
+- **Pass-through attrs**: Unrecognized `<odac:input ...>` attributes are preserved into generated HTML input/textarea/input[type=file].
 - **Skip persistence**: Use `skip` on `<odac:input>` to validate a field but exclude it from final payload.
 - **Unique shorthand**: `unique` attribute on `<odac:input>` enables auth-register uniqueness list.
 
+## File Upload Fields
+
+File inputs work end-to-end with zero-config validation, like all other input types:
+
+```html
+<odac:form action="Profile.saveAvatar" enctype="multipart/form-data">
+  <odac:input type="file" name="avatar" label="Avatar">
+    <odac:validate rule="required|maxsize:2MB|mimetype:image/png,image/jpeg" message="PNG/JPEG, max 2MB"/>
+  </odac:input>
+  <odac:submit text="Save"/>
+</odac:form>
+```
+
+### File Rules
+- **`required`**: file must be present (at least one file for `multiple`).
+- **`maxsize:2MB`** / **`minsize:10KB`**: size constraints (supports B, KB, MB, GB suffixes); enforced server-side via busboy limits + client-side byte checks.
+- **`mimetype:image/png,image/jpeg`** (alias **`accept:`**): comma-separated MIME list; wildcards like `image/*` supported. Validated via claimed MIME, extension map, and (for images) magic-byte sniffing.
+- **`ext:jpg,png`**: file extension whitelist (case-insensitive).
+- **`maxfiles:3`**: max file count for `multiple` inputs.
+
+### Controller Access
+In action forms, access uploaded files via `form.file(name)`:
+```javascript
+async saveAvatar(form) {
+  const avatar = await form.file('avatar')
+  if (!avatar) return form.error('avatar', 'No file uploaded')
+  
+  const dest = await avatar.move(`${__dir}/storage/avatars/${user.id}.${avatar.ext}`)
+  user.avatar = dest
+  return form.success('Avatar saved')
+}
+```
+
+### Table Forms
+For `table="..."` forms, file fields are auto-stored relative to `uploadDir` (configured in `odac.json` or `$ODAC_UPLOAD_DIR`) and the path string is persisted in the column.
+
+### File Object Shape
+```javascript
+{
+  field: 'avatar',
+  name: 'photo.jpg',       // original filename
+  ext: 'jpg',              // extension (lowercase)
+  mimetype: 'image/jpeg',  // client-claimed
+  size: 123456,            // bytes
+  path: '/tmp/odac-...',   // temp path (null if truncated)
+  truncated: false,        // true if size > maxFileSize
+  stored: false,           // true after move()
+  async move(dest) {...}   // move to permanent location
+}
+```
+
 ## Patterns
 ```javascript
 // Custom form action in class/Contact.js

package/docs/ai/skills/backend/validation.md

@@ -37,7 +37,7 @@ module.exports = async Odac => {
 - `post(key)`: Validate POST payload field.
 - `get(key)`: Validate querystring field.
 - `var(name, value)`: Validate computed/custom value.
-- `file(name)`: Validate uploaded file object.
+- `file(name)`: Validate uploaded file(s) object.
 - `check(rules | boolean)`: Apply pipe rules or direct boolean validation.
 - `message(text)`: Set message for the latest check on current field.
 - `error()`: Runs validation and returns `true` if any error exists.
@@ -65,6 +65,14 @@ module.exports = async Odac => {
 - `regex:pattern`
 - `mindate:YYYY-MM-DD`, `maxdate:YYYY-MM-DD`
 
+### File upload rules (for `file()` fields)
+- `required`: file must be present.
+- `maxsize:2MB` / `minsize:10KB`: size limits (B, KB, MB, GB suffixes).
+- `mimetype:image/png,image/jpeg`: MIME type whitelist; wildcards like `image/*` supported. Validated via claimed MIME, extension map, and (for images) magic-byte sniffing to detect spoofing.
+- `accept:...`: alias for `mimetype:`.
+- `ext:jpg,png`: file extension whitelist (case-insensitive, comma-separated).
+- `maxfiles:N`: max file count for `multiple` file inputs.
+
 ### Auth/security rules
 - `usercheck`: Must be authenticated.
 - `user:field`: Input must match authenticated user field.
@@ -125,7 +133,27 @@ module.exports = async Odac => {
 }
 ```
 
-### 4) Brute-force on auth endpoint
+### 4) File upload validation
+```javascript
+module.exports = async Odac => {
+  const validator = Odac.validator()
+
+  validator.file('avatar').check('required|maxsize:2MB|mimetype:image/png,image/jpeg')
+    .message('Avatar required (PNG/JPEG, max 2MB)')
+  validator.file('documents').check('maxfiles:5|ext:pdf,docx')
+    .message('Max 5 PDFs/Word docs allowed')
+
+  if (await validator.error()) return await validator.result('Upload validation failed')
+  
+  // Access files in controller
+  const avatar = await Odac.file('avatar')
+  await avatar.move(`${__dir}/storage/avatars/${user.id}.${avatar.ext}`)
+  
+  return await validator.success('Files uploaded')
+}
+```
+
+### 5) Brute-force on auth endpoint
 ```javascript
 module.exports = async Odac => {
   const validator = Odac.validator()

package/docs/backend/05-forms/01-custom-forms.md

@@ -105,6 +105,16 @@ Supports all standard HTML input types:
   <odac:validate rule="minlen:2" message="Name must be at least 2 characters"/>
   <odac:validate rule="maxlen:50" message="Name is too long"/>
 </odac:input>
+
+<!-- File upload -->
+<odac:input name="avatar" type="file" label="Profile Picture">
+  <odac:validate rule="required|maxsize:2MB|mimetype:image/png,image/jpeg" message="PNG or JPEG, max 2MB"/>
+</odac:input>
+
+<!-- Multiple file upload -->
+<odac:input name="documents" type="file" label="Documents" multiple>
+  <odac:validate rule="maxfiles:5|ext:pdf,docx" message="Max 5 PDFs or Word docs"/>
+</odac:input>
 ```
 
 ### Field Attributes
@@ -130,6 +140,7 @@ Add validation rules to fields:
 
 ### Available Rules
 
+#### Text/Input Rules
 - `required` - Field is required
 - `email` - Must be valid email
 - `url` - Must be valid URL
@@ -142,6 +153,15 @@ Add validation rules to fields:
 - `alphanumeric` - Letters and numbers only
 - `accepted` - Checkbox must be checked
 
+#### File Upload Rules
+- `required` - File must be provided
+- `maxsize:2MB` - Maximum file size (supports B, KB, MB, GB)
+- `minsize:10KB` - Minimum file size
+- `mimetype:image/png,image/jpeg` - Allowed MIME types (comma-separated; wildcards like `image/*` supported)
+- `accept:...` - Alias for `mimetype:`
+- `ext:jpg,png` - Allowed file extensions (case-insensitive)
+- `maxfiles:5` - Maximum number of files for `multiple` uploads
+
 ### Multiple Rules
 
 Combine rules with `|`:
@@ -306,6 +326,38 @@ module.exports = class Contact {
 
 **Note:** No route definition is needed for the action! The form system handles the routing securely.
 
+## File Upload Handling
+
+Access uploaded files in your controller via `form.file(name)`:
+
+```javascript
+module.exports = class Profile {
+  constructor(Odac) {
+    this.Odac = Odac
+  }
+
+  async updateAvatar(form) {
+    const avatar = await form.file('avatar')
+    if (!avatar) {
+      return form.error('avatar', 'No file uploaded')
+    }
+
+    // Store the file permanently
+    const userId = this.Odac.Auth.user('id')
+    const dest = await avatar.move(`${__dir}/../storage/avatars/${userId}.${avatar.ext}`)
+    
+    // Update user record with file path
+    // await this.Odac.DB.users.where('id', userId).update({avatar: dest})
+    
+    return form.success('Avatar updated!', '/profile')
+  }
+}
+```
+
+For `table="..."` forms with file fields, files are automatically stored in the configured `uploadDir` and the file path is saved to the database column.
+
+> **Security:** `move(dest)` writes to whatever path you pass, just like `fs` — the file object's own `.name` is already stripped to a bare filename, but if you build `dest` from raw user input, sanitize it yourself to avoid path traversal. Server-generated names (as in the example above) are always safe. Uploads are validated for size/type before your handler runs, but content sniffing only covers raster images (JPEG/PNG/GIF/WebP); other types are trusted by extension + declared MIME, and `image/*` also permits SVG (an XSS vector) — list explicit types like `mimetype:image/png,image/jpeg` when you need to exclude it.
+
 ## Automatic Database Insert
 
 Forms can automatically insert data into database without writing a controller:

package/docs/backend/09-validation/01-the-validator-service.md

@@ -72,6 +72,15 @@ if (await validator.error()) {
 - `regex:pattern` - Must match regex pattern
 - `!disposable` - Block disposable/temporary email providers (List is automatically updated daily)
 
+**File Upload Validation:**
+- `required` - File must be uploaded
+- `maxsize:2MB` - Maximum file size (B, KB, MB, GB)
+- `minsize:10KB` - Minimum file size
+- `mimetype:image/png,image/jpeg` - Allowed MIME types (comma-separated; wildcards like `image/*` supported)
+- `accept:...` - Alias for `mimetype:`
+- `ext:jpg,png` - Allowed file extensions (case-insensitive)
+- `maxfiles:5` - Max files for multi-upload
+
 **Security:**
 - `xss` - Check for HTML tags (XSS protection)
 - `usercheck` - User must be authenticated
@@ -358,6 +367,37 @@ module.exports = async function (Odac) {
 }
 ```
 
+#### Example: File Upload Validation
+
+```javascript
+module.exports = async function (Odac) {
+  const validator = Odac.Validator
+
+  validator
+    .file('avatar')
+    .check('required').message('Avatar is required')
+    .check('maxsize:2MB').message('Avatar must not exceed 2MB')
+    .check('mimetype:image/png,image/jpeg').message('Avatar must be PNG or JPEG')
+
+  validator
+    .file('documents')
+    .check('maxfiles:5').message('Maximum 5 documents allowed')
+    .check('ext:pdf,docx').message('Only PDF and Word documents allowed')
+
+  if (await validator.error()) {
+    return validator.result('Upload validation failed')
+  }
+
+  // Access and store the files
+  const avatar = await Odac.file('avatar')
+  const userId = Odac.Auth.user('id')
+  
+  await avatar.move(`${__dir}/../storage/avatars/${userId}.${avatar.ext}`)
+
+  return validator.success('Files uploaded successfully')
+}
+```
+
 #### Frontend Integration
 
 When using `Odac.form()` on the frontend, validation errors are automatically displayed:

package/docs/backend/13-utilities/02-ipc.md

@@ -72,6 +72,29 @@ await Odac.Ipc.publish('chat:global', { user: 'Emre', text: 'Hello World' });
 > [!TIP]
 > When using `memory` driver, the subscription listener is registered in the current worker. When a message is published, it goes to the Main process and is then broadcasted to all subscribed workers.
 
+#### Unsubscribing
+
+A channel can carry several independent subscribers, so a subscription is identified by its callback — not by the channel name alone. `subscribe()` returns a handle that removes exactly the subscription it created, which saves you from holding on to the callback yourself.
+
+```javascript
+const stats = await Odac.Ipc.subscribe('server:1:stream', onStats); // long-lived
+const ack = await Odac.Ipc.subscribe('server:1:stream', onAck);     // short-lived
+
+await ack.unsubscribe();          // only onAck stops; onStats keeps receiving
+```
+
+`unsubscribe(channel, callback)` does the same thing when you already hold the callback. To drop every subscriber on a channel at once, ask for it explicitly:
+
+```javascript
+await Odac.Ipc.unsubscribeAll('server:1:stream');
+```
+
+> [!WARNING]
+> `unsubscribe(channel)` without a callback cannot tell which subscriber is leaving, so it does nothing and logs a warning. It will throw in the next major version — pass the callback or the handle, or use `unsubscribeAll()`.
+
+> [!TIP]
+> Subscriptions created through the request-scoped `Odac.Ipc` are released automatically when the request ends, so you only need to unsubscribe by hand for subscriptions that should end earlier than the request.
+
 ### Atomic Counters
 
 Use `incrBy` / `decrBy` to atomically increment or decrement a numeric key. These are safe to call from multiple workers simultaneously — no read-then-write race conditions.
@@ -186,5 +209,7 @@ try {
 | `srem(key, ...members)` | Remove members from a set |
 | `lock(key, ttl)` | Acquire a mutex lock |
 | `unlock(key)` | Release a mutex lock |
-| `subscribe(channel, handler)` | Subscribe to a Pub/Sub channel |
+| `subscribe(channel, handler)` | Subscribe to a Pub/Sub channel; returns a handle with `unsubscribe()` |
+| `unsubscribe(channel, handler)` | Remove a single subscription, leaving other subscribers intact |
+| `unsubscribeAll(channel)` | Remove every subscription on a channel |
 | `publish(channel, message)` | Publish a message to a channel |

package/docs/frontend/03-forms/01-form-handling.md

@@ -174,43 +174,60 @@ Odac.form('#my-form', function(data) {
 
 ## File Uploads
 
-### Basic File Upload
+### Basic File Upload with `<odac:form>`
+
+File upload in Odac forms is seamless — just add a `type="file"` input and validation rules:
 
 ```html
-<form id="upload-form" action="/api/upload" method="POST">
-  <input name="file" type="file" required>
-  <button type="submit">Upload</button>
-</form>
+<odac:form action="Profile.saveAvatar" id="avatar-form">
+  <odac:input type="file" name="avatar" label="Profile Picture">
+    <odac:validate rule="required|maxsize:2MB|mimetype:image/png,image/jpeg" message="PNG/JPEG, max 2MB"/>
+  </odac:input>
+  <odac:submit text="Upload"/>
+</odac:form>
 ```
 
 ```javascript
-Odac.form('#upload-form', function(data) {
+Odac.form('#avatar-form', function(data) {
   if (data.result.success) {
-    console.log('File uploaded:', data.result.filename)
+    alert('Avatar uploaded!')
   }
 })
 ```
 
-### Upload Progress
+**Features:**
+- ✅ Client-side validation (size, MIME type, extension)
+- ✅ Server-side validation with magic-byte sniffing for images
+- ✅ Automatic multipart/form-data handling
+- ✅ File size progress tracking
+
+### Upload Progress Tracking
 
 ```javascript
 Odac.form({
-  form: '#upload-form',
+  form: '#avatar-form',
   loading: function(percent) {
     document.querySelector('#progress').style.width = percent + '%'
-    document.querySelector('#progress-text').textContent = percent + '%'
   }
 }, function(data) {
-  console.log('Upload complete!')
+  if (data.result.success) {
+    console.log('Upload complete!')
+  }
 })
 ```
 
-### Multiple Files
+### Multiple File Upload
+
+For multiple file selection, add the `multiple` attribute and use `maxfiles` validation:
 
 ```html
-<input name="files[]" type="file" multiple>
+<odac:input type="file" name="documents" label="Documents" multiple>
+  <odac:validate rule="maxfiles:5|ext:pdf,docx" message="Max 5 PDFs/Word docs"/>
+</odac:input>
 ```
 
+**Note:** File inputs are never repopulated on validation error (for security). Users must re-select files after an error.
+
 ## Advanced Features
 
 ### Disable Messages

package/package.json

@@ -7,7 +7,7 @@
     "email": "mail@emre.red",
     "url": "https://emre.red"
   },
-  "version": "1.4.15",
+  "version": "1.4.17",
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"
@@ -22,6 +22,7 @@
   },
   "dependencies": {
     "@tailwindcss/cli": "^4.1.18",
+    "busboy": "^1.6.0",
     "esbuild": "^0.25.12",
     "knex": "^3.1.0",
     "lmdb": "^3.4.4",