# Read - Unified Read Pipeline

The `read` block owns the read side of every resource: the collection-level
`GET /` endpoint, single-record `GET /:id`, and named view projections. It
replaces the legacy `crud.list` and `crud.get` shapes — those are rejected
at compile time in DSL v2.

## Basic Usage

```typescript
// features/customers/customers.ts
import { sqliteTable, text } from 'drizzle-orm/sqlite-core';
import { defineTable } from '@quickback/compiler';

export const customers = sqliteTable('customers', {
  id: text('id').primaryKey(),
  name: text('name').notNull(),
  email: text('email').notNull(),
  ssn: text('ssn'),
  status: text('status').notNull(),
  organizationId: text('organization_id').notNull(),
});

export default defineTable(customers, {
  firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
  masking: {
    ssn: { type: 'ssn', show: { roles: ['admin'] } },
  },
  read: {
    access: { roles: ['member', 'admin'] },
    views: {
      summary: {
        fields: ['id', 'name', 'status'],
        access: { roles: ['member', 'admin'] },
      },
      full: {
        fields: ['id', 'name', 'email', 'ssn', 'status'],
        access: { roles: ['admin'] },
      },
    },
  },
  create: { access: { roles: ['admin'] } },
  update: { access: { roles: ['admin'] } },
  delete: { access: { roles: ['admin'] }, mode: 'soft' },
});
```

## What `read` Owns

| Endpoint | Gate |
|----------|------|
| `GET /api/v1/{resource}` | `read.access` |
| `GET /api/v1/{resource}/:id` | `read.access` |
| `GET /api/v1/{resource}/views/{name}` | `read.views[name].access` (falls back to `read.access`) |

Single-record `GET /:id` inherits `read.access` automatically — there's no
separate `read.get` block. If you need different access for single records,
use record-level conditions on `read.access`:

```typescript
read: {
  access: {
    or: [
      { roles: ['admin'] },
      { roles: ['member'], record: { ownerId: { equals: '$ctx.userId' } } },
    ],
  },
}
```

## Configuration Options

```typescript
interface ReadConfig {
  // Role/condition gate for collection reads, single-record reads, and the
  // default view fallback.
  access?: Access;

  // Optional read-side firewall override. If omitted, the resource-level
  // `firewall` block is used (the common case).
  firewall?: FirewallConfig;

  // Pagination defaults for collection reads.
  pageSize?: number;       // Default page size (default: 50)
  maxPageSize?: number;    // Hard cap (default: 100)

  // Named field projections. Each view has its own access and field list.
  views?: {
    [viewName: string]: ViewConfig;
  };
}

interface ViewConfig {
  fields: string[];        // Columns returned by this view
  access?: Access;         // Per-view access (falls back to read.access)
  pageSize?: number;
  maxPageSize?: number;
}
```

## Access Ordering on `/:id`

Single-record `GET /:id` evaluates checks in this order to close the
404-vs-403 ID-probe channel:

1. **Auth gate** — 401 if unauthenticated
2. **Pre-record access** — role-only check (skips `access.record` predicates)
3. **Firewall query** — `WHERE` clause filters by ownership
4. **Post-record access** — full check including record-level predicates
5. **Masking** — applied to the response

An unauthorized caller without a matching role gets 403 from step 2 before
the database is touched, so they can't distinguish "row exists in another
tenant" from "row doesn't exist." A caller with the right role but the wrong
tenant gets the firewall's configured response (403 by default; see
[`firewallErrorMode: 'hide'`](/compiler/definitions/firewall) for an opaque
404 instead).

Function-form access is opaque to the pre-check (it always passes there) and
is fully evaluated post-record, so `access: async (ctx, record) => ...`
still works as before.

## Views Under `read.views`

Views are named field projections — Column Level Security. They live under
`read.views` (not at the resource top level). See
[Views](/compiler/definitions/views) for the full feature reference.

```typescript
read: {
  access: { roles: ['member', 'admin'] },
  views: {
    public: {
      fields: ['id', 'title', 'status'],
      access: { roles: ['PUBLIC'] },
    },
    internal: {
      fields: ['id', 'title', 'status', 'salaryMin', 'salaryMax'],
      access: { roles: ['admin'] },
    },
  },
}
```

Named views are emitted at dedicated path routes:

- `GET /api/v1/jobs/views/internal`
- If `read.defaultView` is set, bare `GET /api/v1/jobs` resolves to that view.

## Migrating from `crud.list` / `crud.get`

DSL v2 rejects both at compile time. The migration is mechanical:

| Before (DSL v1) | After (DSL v2) |
|---|---|
| `crud.list.access` | `read.access` |
| `crud.list.pageSize` | `read.pageSize` |
| `crud.list.maxPageSize` | `read.maxPageSize` |
| `crud.list.fields: [...]` | Move to a named view under `read.views` |
| `crud.get.access` | `read.access` (or record-level conditions) |
| `crud.get.fields: [...]` | Move to a named view; clients call `/views/{name}` |
| Top-level `views: {...}` | `read.views: {...}` |

Example before/after:

```typescript
// Before — DSL v1
crud: {
  list: {
    access: { roles: ['member'] },
    pageSize: 25,
  },
  get: {
    access: { roles: ['member'] },
    fields: ['id', 'name', 'status'],   // per-field projection
  },
  create: { access: { roles: ['admin'] } },
}

// After — DSL v2
read: {
  access: { roles: ['member'] },
  pageSize: 25,
  views: {
    summary: {
      fields: ['id', 'name', 'status'],
      access: { roles: ['member'] },
    },
  },
}
create: { access: { roles: ['admin'] } }
```

Clients that previously hit `GET /:id` to retrieve only summary fields now
move that projection to a named collection view such as
`GET /api/v1/jobs/views/summary`. Single-record `GET /:id` always returns the
full masked record.

## Read-Only Resources

A resource that exposes only reads is valid with no write-operation blocks at all:

```typescript
export default defineTable(balanceSnapshots, {
  firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
  read: { access: { roles: ['member', 'admin'] } },
  // no create/update/delete/upsert — no writes
});
```

## See Also

- [Views](/compiler/definitions/views) — Full reference for named projections
- [Access](/compiler/definitions/access) — Roles, record conditions, and combinators
- [Firewall](/compiler/definitions/firewall) — Tenant scoping and `firewallErrorMode`
- [Views API](/compiler/targets/hono-api/using-the-api/views-api) — Calling views from clients
