@cuboapp/api-backend 3.0.15 → 4.0.0

package/src/helpers/index.ts

@@ -9,7 +9,8 @@ import {
   CUBO_CRUD_MAX_PAGE_LIMIT,
   CUBO_CRUD_QUERY_CONDITION,
   CUBO_CRUD_QUERY_KEY_REGEX,
-  CUBO_CRUD_QUERY_SYMBOL_NOT
+  CUBO_CRUD_QUERY_SYMBOL_NOT,
+  CUBO_CRUD_QUERY_SYMBOL_OR
 } from '../constants'
 import type { CuboBackendApi } from '../core'
 import { CuboDialect, getDialect } from '../dialects'
@@ -69,37 +70,61 @@ export class ApiHelpers<T extends CuboApiEntitiesMap<T>, A = unknown> {
     let is_not = false
     let condition = 'eq'
 
+    // Read the condition off the PREFIX when the value carries one, and leave the rest verbatim.
+    //
+    // The parse below derives the condition by counting `value.split(':')`, which means a value
+    // containing a colon of its own has no way through it: `gte:2026-08-01 00:00:00` is four parts
+    // and gets rejected, as does a `btw` whose bounds are timestamps. Timestamps are the obvious
+    // case, but any text with a colon in it has the same problem.
+    //
+    // Only a RECOGNISED `[not:]<condition>:` prefix takes this path, so nothing that works today
+    // changes and nothing that is rejected today is quietly accepted: `typo:5` still has no known
+    // condition, still falls through, and still fails loudly. A `btw` range whose bounds are
+    // themselves colon-bearing separates them with `..` rather than `:`.
+    // Longest first, so `gte` is not shadowed by `gt` and `ilike` not by `in`.
+    const known = Object.values(CUBO_CRUD_QUERY_CONDITION)
+      .slice()
+      .sort((a, b) => b.length - a.length)
+      .join('|')
+    const prefixed = typeof value === 'string' ? new RegExp(`^(${CUBO_CRUD_QUERY_SYMBOL_NOT}:)?(${known}):`).exec(value) : null
+
     // condition parts
-    switch (parts.length) {
-      case 3:
-        if (parts[0] === 'btw') {
-          condition = parts[0]
-          value = `${parts[1]}:${parts[2]}`
-        } else if (parts[0] !== CUBO_CRUD_QUERY_SYMBOL_NOT) {
-          throw new Error(`"${field.alias}": three-level value allow only "not" condition at first level (${value})`)
-        } else if (!Object.values(CUBO_CRUD_QUERY_CONDITION).includes(parts[1])) {
-          throw new Error(`"${field.alias}": incorrect condition "${parts[1]}" in second level (${value})`)
-        } else {
-          is_not = true
-          condition = parts[1]
-          value = parts[2]
-        }
-        break
-      case 2:
-        if (parts[0] === CUBO_CRUD_QUERY_SYMBOL_NOT) {
-          is_not = true
-          value = parts[1]
-        } else if (Object.values(CUBO_CRUD_QUERY_CONDITION).includes(parts[0])) {
-          condition = parts[0]
-          value = parts[1]
-        } else {
-          throw new Error(`"${field.alias}": incorrect condition "${parts[0]}" in second level (${value})`)
-        }
-        break
-      case 1:
-        break
-      default:
-        throw new Error(`"${field.alias}": incorrect condition value "${value}"`)
+    if (prefixed) {
+      is_not = Boolean(prefixed[1])
+      condition = prefixed[2]
+      value = (value as string).slice(prefixed[0].length)
+    } else {
+      switch (parts.length) {
+        case 3:
+          if (parts[0] === 'btw') {
+            condition = parts[0]
+            value = `${parts[1]}:${parts[2]}`
+          } else if (parts[0] !== CUBO_CRUD_QUERY_SYMBOL_NOT) {
+            throw new Error(`"${field.alias}": three-level value allow only "not" condition at first level (${value})`)
+          } else if (!Object.values(CUBO_CRUD_QUERY_CONDITION).includes(parts[1])) {
+            throw new Error(`"${field.alias}": incorrect condition "${parts[1]}" in second level (${value})`)
+          } else {
+            is_not = true
+            condition = parts[1]
+            value = parts[2]
+          }
+          break
+        case 2:
+          if (parts[0] === CUBO_CRUD_QUERY_SYMBOL_NOT) {
+            is_not = true
+            value = parts[1]
+          } else if (Object.values(CUBO_CRUD_QUERY_CONDITION).includes(parts[0])) {
+            condition = parts[0]
+            value = parts[1]
+          } else {
+            throw new Error(`"${field.alias}": incorrect condition "${parts[0]}" in second level (${value})`)
+          }
+          break
+        case 1:
+          break
+        default:
+          throw new Error(`"${field.alias}": incorrect condition value "${value}"`)
+      }
     }
 
     switch (field.type) {
@@ -158,7 +183,7 @@ export class ApiHelpers<T extends CuboApiEntitiesMap<T>, A = unknown> {
                 if ([CUBO_CRUD_QUERY_CONDITION.IN, CUBO_CRUD_QUERY_CONDITION.NIN].includes(condition)) {
                   value = value.split(',').map(Number)
                 } else if (condition === CUBO_CRUD_QUERY_CONDITION.BTW) {
-                  const [fromStr, toStr] = value.split(':')
+                  const [fromStr, toStr] = value.includes('..') ? value.split('..') : value.split(':')
                   const from = precision === 0 ? parseInt(fromStr) : parseFloat(fromStr)
                   const to = precision === 0 ? parseInt(toStr) : parseFloat(toStr)
 
@@ -284,7 +309,10 @@ export class ApiHelpers<T extends CuboApiEntitiesMap<T>, A = unknown> {
         replacements[replacement] = value
         break
       case CUBO_CRUD_QUERY_CONDITION.BTW: {
-        const [from, to] = String(value).split(':')
+        // `..` when the bounds carry their own colons (timestamps), `:` otherwise. Splitting on `:`
+        // unconditionally would take `00` as the whole upper bound of a `10:00:00` range.
+        const raw = String(value)
+        const [from, to] = raw.includes('..') ? raw.split('..') : raw.split(':')
         const fromKey = `${replacement}_from`
         const toKey = `${replacement}_to`
 
@@ -464,7 +492,7 @@ export class ApiHelpers<T extends CuboApiEntitiesMap<T>, A = unknown> {
     return this.api.options.entities.find((e) => e.alias === alias)
   }
 
-  public async getEntityById(id: number): Promise<CuboEntity | undefined> {
+  public async getEntityById(id: string): Promise<CuboEntity | undefined> {
     return this.api.options.entities.find((e) => e.id === id)
   }
 
@@ -488,31 +516,58 @@ export class ApiHelpers<T extends CuboApiEntitiesMap<T>, A = unknown> {
     const { sort, limit: _limit, page, with: _withes, ...query } = cloneDeep(req.query || {})
 
     // plain conditions (nested are in withes.ts)
+    //
+    // Counted, because a field can now legitimately be named by two different keys — `?a=1&a|b=2` —
+    // and a replacement name derived from the field alone would have the second silently overwrite
+    // the first, changing what the first condition filters on rather than failing.
+    let conditionIndex = 0
     for (const key in query || {}) {
       const parts = key.replace(CUBO_CRUD_QUERY_KEY_REGEX, '')?.split('.')
 
       if (parts.length === 1) {
-        const conditionField = entity.fields?.find((f) => f.alias === parts[0])
-        const defaultField = CUBO_CRUD_DEFAULT_FIELDS.find((f) => f.alias === parts[0])
-
-        // if (!conditionField && !defaultField) {
-        //   throw new Error('condition field "' + parts[0] + '" not found in entity "' + entity.alias + '"')
-        // }
+        // A key may name several fields to be OR-ed: `?a|b=<value>` asks the same condition of each
+        // and matches a row where ANY of them holds. One field is just the one-element case, so
+        // there is a single path through here rather than two that can drift apart.
+        const aliases = parts[0].split(CUBO_CRUD_QUERY_SYMBOL_OR).filter((a) => a.length > 0)
+        if (!aliases.length) continue
+        conditionIndex += 1
+
+        const anyOf: string[] = []
+        for (const alias of aliases) {
+          const conditionField = entity.fields?.find((f) => f.alias === alias)
+          const defaultField = CUBO_CRUD_DEFAULT_FIELDS.find((f) => f.alias === alias)
+
+          if (!conditionField && !defaultField) {
+            throw new Error('condition field "' + alias + '" not found in entity "' + entity.alias + '"')
+          }
 
-        if (conditionField || defaultField) {
-          const fieldAlias = conditionField ? conditionField.alias : defaultField!.alias
-          const preparedCondition = this.clearFieldConditionValue(conditionField ? conditionField : defaultField!, query[key])
+          // Upstream replaced the throw above with `if (conditionField || defaultField)`, skipping an
+          // unknown field silently. Not adopted: a filter naming a field that does not exist is a
+          // caller mistake, and answering it with an unfiltered list is the wrong answer delivered
+          // confidently. The throw is also what our OR-alias loop needs — a skipped alias would make
+          // `a|b` quietly mean `b`.
+          const field = conditionField ?? defaultField!
+          const preparedCondition = this.clearFieldConditionValue(field, query[key])
           const prepared = this.prepareConditionSql(
-            `t1.${fieldAlias}`,
-            `c_1_${fieldAlias}_value`,
+            `t1.${field.alias}`,
+            // `conditionIndex` is OURS and upstream still names the parameter after the field alone.
+            // Two conditions on one field then bind the same name and the second silently overwrites
+            // the first — which is how the documents list lost its filters (f5eb8de).
+            `c_1_${conditionIndex}_${field.alias}_value`,
             preparedCondition.value,
             preparedCondition.condition,
             preparedCondition.is_not
           )
 
-          conditions.push(...(prepared.conditions || []))
+          anyOf.push(...(prepared.conditions || []))
           Object.assign(replacements, prepared.replacements || {})
         }
+
+        // Parenthesised as one condition. The caller AND-s the list, so an unwrapped `a or b` would
+        // bind looser than the surrounding ANDs and quietly widen every other filter on the query.
+        // Upstream pushes the parts straight into `conditions`, which has that effect.
+        if (anyOf.length === 1) conditions.push(anyOf[0])
+        else if (anyOf.length > 1) conditions.push(`(${anyOf.join(' or ')})`)
       }
     }
 

package/src/helpers/withes.ts

@@ -69,7 +69,7 @@ export class ApiHelpersWithes<T extends CuboApiEntitiesMap<T>> {
 
       // если нашли кастомное поле
       if (joinCustomField) {
-        const relation_entity_id: number | undefined = joinCustomField?.extra?.select_entity_id
+        const relation_entity_id: string | undefined = joinCustomField?.extra?.select_entity_id
         const relation_entity_alias: keyof T | undefined = joinCustomField?.extra?.select_entity_alias as keyof T
 
         if (!relation_entity_id && !relation_entity_alias) {

package/src/hooks/index.ts

@@ -1,3 +1,4 @@
 export * from './constants'
 export * from './types'
 export * from './define'
+export * from './subscribe'

package/src/hooks/subscribe.ts

@@ -0,0 +1,160 @@
+/**
+ * Subscribing a module backend to its declared hooks (hooks.md §5).
+ *
+ * A module's hooks are declared on its version, next to the entities they belong to. This is the
+ * other half: the running build telling the core "I am alive, I am this version, and these are the
+ * tuples I actually implement". The core binds the declarations to this process, works out which
+ * accounts that touches — a module backend serves every account it is installed in and deliberately
+ * cannot enumerate them — and compiles the chain.
+ *
+ * What a module backend has to write is one call:
+ *
+ *     const stop = subscribeHooks({
+ *       apiUrl: process.env.CUBO_API_URL!,
+ *       token: process.env.CUBO_TOKEN!,
+ *       version: process.env.CUBO_MODULE_VERSION!,
+ *       baseUrl: 'http://flowers-be:9100',
+ *       implemented: tuplesFrom(READS, ENRICH, AFTER, VIRTUAL_FIELDS)
+ *     })
+ *
+ * and call `stop()` on shutdown. Everything else — the renewal interval, the TTL contract, the boot
+ * diff, the graceful unsubscribe — lives here so no module has to reimplement a protocol.
+ */
+
+/** How often to renew. The core treats a subscription older than 30s as dead, so this has slack. */
+export const SUBSCRIBE_INTERVAL_MS = 10_000
+
+export interface SubscribeOptions {
+  /** The core API base url, e.g. `http://cubo-api:4000`. */
+  apiUrl: string
+  /** This service's `cubo-module-service` token — the same one `/auth/me` accepts. */
+  token: string
+  /** The module VERSION id this build implements. Hooks are a contract with one specific build. */
+  version: string
+  /**
+   * Where this service can be reached, e.g. `http://flowers-be:9100`.
+   *
+   * Honoured only for the module owner's own account. Everywhere else the core resolves the endpoint
+   * from the deployment record instead — the hook url is where the instance sends a live,
+   * identity-scoped credential, so it must not be settable by whoever holds this token.
+   */
+  baseUrl?: string
+  /** The tuples this build implements: `entity:method:phase`. See `hookTuples`. */
+  implemented: string[]
+  /** Called with the core's boot diff on every successful subscribe. */
+  onDiff?: (diff: SubscribeDiff) => void
+  /** Called when a renewal fails. Default logs; the loop keeps trying. */
+  onError?: (error: unknown) => void
+  fetchImpl?: typeof fetch
+}
+
+export interface SubscribeDiff {
+  declared: string[]
+  /** Declared but not implemented by this build. */
+  missing: string[]
+  /** The subset of `missing` the module marked required — every write on those will fail closed. */
+  missing_required: string[]
+  /** Implemented but never declared. Harmless (the core will not call them) but usually an oversight. */
+  undeclared: string[]
+}
+
+/**
+ * Turn a module's dispatch maps into the tuple list the core diffs against.
+ *
+ * Module backends key their handlers by `entity:method` and split before/after by route, which is the
+ * convention the declaration format was lifted FROM — so the tuples can be derived from the code
+ * rather than maintained beside it. Anything derived cannot drift.
+ */
+export function hookTuples(maps: {
+  /** Read rewrites — before-phase on the methods each key names. */
+  before?: Record<string, unknown>
+  /** Response shaping / write effects — after-phase. */
+  after?: Record<string, unknown>
+  /** Entities whose write bodies are stripped before the engine sees them: create + update, before. */
+  virtualFields?: string[] | Record<string, unknown>
+}): string[] {
+  const out = new Set<string>()
+  for (const key of Object.keys(maps.before ?? {})) out.add(`${key}:before`)
+  for (const key of Object.keys(maps.after ?? {})) out.add(`${key}:after`)
+  const virtual = Array.isArray(maps.virtualFields) ? maps.virtualFields : Object.keys(maps.virtualFields ?? {})
+  for (const entity of virtual) {
+    out.add(`${entity}:create:before`)
+    out.add(`${entity}:update:before`)
+  }
+  return [...out].sort()
+}
+
+export interface Subscription {
+  /** Unsubscribe and stop renewing. Safe to call more than once. */
+  stop: () => Promise<void>
+  /** Force a renewal now — useful in tests, and after a deploy changes what is implemented. */
+  renew: () => Promise<SubscribeDiff | null>
+}
+
+/**
+ * Start the subscribe loop. Returns immediately; the first renewal runs in the background so a slow
+ * or unreachable core cannot hold up the service's own boot.
+ */
+export function subscribeHooks(options: SubscribeOptions): Subscription {
+  const fetchImpl = options.fetchImpl ?? fetch
+  const url = `${options.apiUrl.replace(/\/+$/, '')}/modules-api/subscription`
+  const headers = { 'content-type': 'application/json', 'cubo-module-service': options.token }
+  const onError =
+    options.onError ??
+    ((error: unknown) => {
+      // eslint-disable-next-line no-console
+      console.error('[hooks] subscribe failed:', error instanceof Error ? error.message : String(error))
+    })
+
+  let timer: ReturnType<typeof setInterval> | null = null
+  let stopped = false
+
+  async function renew(): Promise<SubscribeDiff | null> {
+    if (stopped) return null
+    try {
+      const res = await fetchImpl(url, {
+        method: 'PUT',
+        headers,
+        body: JSON.stringify({
+          version: options.version,
+          base_url: options.baseUrl ?? '',
+          implemented: options.implemented
+        })
+      })
+      if (!res.ok) throw new Error(`core replied ${res.status}`)
+      const diff = (await res.json()) as SubscribeDiff
+      // A required tuple this build does not implement is fatal for those writes — say so loudly at
+      // boot rather than letting it surface as an empty `{}` reply at the first save.
+      if (diff.missing_required?.length) {
+        // eslint-disable-next-line no-console
+        console.error(`[hooks] REQUIRED hooks declared but not implemented: ${diff.missing_required.join(', ')}`)
+      }
+      options.onDiff?.(diff)
+      return diff
+    } catch (error) {
+      onError(error)
+      return null
+    }
+  }
+
+  void renew()
+  timer = setInterval(() => void renew(), SUBSCRIBE_INTERVAL_MS)
+  // Never hold the process open on our account: a renewal loop is not a reason not to exit.
+  timer.unref?.()
+
+  return {
+    renew,
+    stop: async () => {
+      if (stopped) return
+      stopped = true
+      if (timer) clearInterval(timer)
+      timer = null
+      try {
+        await fetchImpl(url, { method: 'DELETE', headers })
+      } catch (error) {
+        // A crash-stop is covered by the TTL anyway; failing to say goodbye is not worth an error.
+        onError(error)
+      }
+    }
+  }
+}

package/src/hooks/types.ts

@@ -17,7 +17,7 @@ export type CuboHookCtx<R, A = unknown> = {
   entity: CuboEntity
   req: CuboCrudRequest
   auth?: A
-  performer_id?: number
+  performer_id?: string
   queryOptions: CuboCrudQueryOptions
 }
 
@@ -43,8 +43,11 @@ export interface CuboAugmentation<R, A = unknown> {
   // авторизация конкретного действия над строкой
   can?(action: CuboCrudAction, ctx: CuboHookCtx<R, A> & { row?: R }): MaybePromise<boolean>
 
-  // фильтр строки под CRDT-подписку
-  filterRowForCrdtEvent?(row: R, filters: Record<string, any>): boolean
+  // фильтр строки под CRDT-подписку.
+  // `auth` — авторизация КЛИЕНТА, владеющего подпиской (адаптер резолвит её по subscribe.client_id).
+  // Без неё пуш нельзя ограничить по правам: первичная гидрация подписки идёт через getMany с auth
+  // и уважает beforeGetMany, а живые пуши — нет, и строка, скрытая при гидрации, всё равно долетела бы.
+  filterRowForCrdtEvent?(row: R, filters: Record<string, any>, auth?: A): boolean
 }
 
 export type CuboAugmentationsStore<T extends CuboApiEntitiesMap<T>, A = unknown> = {

package/src/types/basic.ts

@@ -1,7 +1,7 @@
 import { type Transaction } from '@cuboapp/database'
 import { CuboEntity, CuboEntityField } from '@cuboapp/types'
 
-import { CUBO_CRUD_ACTION } from '@/constants'
+import { CUBO_CRUD_ACTION } from '../constants'
 
 export type CuboCrudAction = (typeof CUBO_CRUD_ACTION)[number]
 
@@ -27,7 +27,7 @@ export type CuboCrudRequest = {
 }
 
 export type CuboCrudOptions = {
-  performer_id?: number
+  performer_id?: string
   transaction?: Transaction
 }
 

package/src/types/db.ts

@@ -78,7 +78,7 @@ export const normalizeCuboCrudQueryOptions = (input?: CuboCrudQueryOptionsInput
 
 export type CuboCrudMethodOptions<E extends object = {}> = {
   transaction?: Transaction
-  performer_id?: number
+  performer_id?: string
   auth?: any
   extra?: any
   debounce?: number

package/.prettierrc

@@ -1,8 +0,0 @@
-{
-  "trailingComma": "none",
-  "tabWidth": 2,
-  "semi": false,
-  "singleQuote": true,
-  "eslintIntegration": true,
-  "printWidth": 140
-}

package/tsconfig.build.json

@@ -1,4 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "exclude": ["node_modules", "test", "dist", "**/*spec.ts"]
-}

package/tsconfig.json

@@ -1,22 +0,0 @@
-{
-  "compilerOptions": {
-    "module": "commonjs",
-    "declaration": true,
-    "removeComments": true,
-    "emitDecoratorMetadata": true,
-    "experimentalDecorators": true,
-    "allowSyntheticDefaultImports": true,
-    "target": "ES2021",
-    "sourceMap": true,
-    "rootDir": ".",
-    "incremental": true,
-    "skipLibCheck": true,
-    "strict": false,
-    "paths": {
-      "@/*": ["./src/*"]
-    },
-    "types": ["node"]
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}