@objy/server 0.0.0-stage → 0.1.0

package/src/ndjson.js

@@ -0,0 +1,117 @@
+import { Readable } from "node:stream";
+import { StringDecoder } from "node:string_decoder";
+
+export const NDJSON_CONTENT_TYPE = "application/x-ndjson";
+
+export function isNdjsonContentType(value) {
+  const type = String(value || "").toLowerCase().split(";")[0].trim();
+  return type === "application/x-ndjson" || type === "application/ndjson";
+}
+
+export function acceptsNdjson(headers = {}) {
+  return String(headers.accept || "").toLowerCase().includes("application/x-ndjson") ||
+    String(headers.accept || "").toLowerCase().includes("application/ndjson");
+}
+
+export function ndjsonReadable(values = []) {
+  return Readable.from(ndjsonLines(values));
+}
+
+export async function* parseNdjsonBatches(stream, {
+  maxBatchObjects = 1000,
+  maxBatchBytes = 0,
+  maxObjectBytes = 0,
+  label = "NDJSON",
+} = {}) {
+  let batch = [];
+  let bytes = 0;
+  const maxObjects = Math.max(1, Number(maxBatchObjects) || 1000);
+  const maxBytes = Math.max(0, Number(maxBatchBytes) || 0);
+
+  for await (const entry of parseNdjsonStream(stream, { maxObjectBytes, label })) {
+    if (batch.length && maxBytes && bytes + entry.bytes > maxBytes) {
+      yield batch;
+      batch = [];
+      bytes = 0;
+    }
+    batch.push(entry.value);
+    bytes += entry.bytes;
+    if (batch.length >= maxObjects || (maxBytes && bytes >= maxBytes)) {
+      yield batch;
+      batch = [];
+      bytes = 0;
+    }
+  }
+
+  if (batch.length) yield batch;
+}
+
+export async function* parseNdjsonStream(stream, { maxObjectBytes = 0, label = "NDJSON" } = {}) {
+  const decoder = new StringDecoder("utf8");
+  let buffer = "";
+  let line = 0;
+  const maxBytes = Number(maxObjectBytes) || 0;
+
+  for await (const chunk of asyncIterableStream(stream)) {
+    buffer += decoder.write(Buffer.from(chunk));
+
+    let newline;
+    while ((newline = buffer.indexOf("\n")) !== -1) {
+      const rawLine = stripTrailingCarriageReturn(buffer.slice(0, newline));
+      buffer = buffer.slice(newline + 1);
+      line += 1;
+      if (!rawLine.trim()) continue;
+      yield parseNdjsonLine(rawLine, line, maxBytes, label);
+    }
+
+    if (maxBytes && Buffer.byteLength(buffer) > maxBytes) {
+      throw ndjsonError(413, "object is too large", {
+        line: line + 1,
+        bytes: Buffer.byteLength(buffer),
+        maxObjectBytes: maxBytes,
+      });
+    }
+  }
+
+  buffer += decoder.end();
+  if (buffer.length > 0) {
+    const rawLine = stripTrailingCarriageReturn(buffer);
+    line += 1;
+    if (rawLine.trim()) yield parseNdjsonLine(rawLine, line, maxBytes, label);
+  }
+}
+
+async function* ndjsonLines(values) {
+  for (const value of values || []) {
+    yield `${JSON.stringify(value)}\n`;
+  }
+}
+
+function asyncIterableStream(stream) {
+  if (stream?.[Symbol.asyncIterator]) return stream;
+  if (stream?.getReader) return Readable.fromWeb(stream);
+  return stream || [];
+}
+
+function parseNdjsonLine(rawLine, line, maxObjectBytes, label) {
+  const bytes = Buffer.byteLength(rawLine);
+  if (maxObjectBytes && bytes > maxObjectBytes) {
+    throw ndjsonError(413, "object is too large", { line, bytes, maxObjectBytes });
+  }
+  try {
+    return { line, bytes, value: JSON.parse(rawLine) };
+  } catch {
+    throw ndjsonError(400, `invalid ${label} at line ${line}`, { line });
+  }
+}
+
+function stripTrailingCarriageReturn(value) {
+  return value.endsWith("\r") ? value.slice(0, -1) : value;
+}
+
+function ndjsonError(status, message, body) {
+  const err = new Error(message);
+  err.status = status;
+  err.body = { error: message, ...body };
+  return err;
+}

package/src/node-runtime.js

@@ -0,0 +1,29 @@
+import { getHeapStatistics } from "node:v8";
+import { constants, deflateSync, inflateSync } from "node:zlib";
+
+export function encodeUtf8(value) {
+  return Buffer.from(String(value));
+}
+
+export function decodeUtf8(value) {
+  return Buffer.from(value.buffer, value.byteOffset, value.byteLength).toString("utf8");
+}
+
+export function compress(value) {
+  const compressed = deflateSync(value, { level: constants.Z_BEST_SPEED });
+  const compact = new Uint8Array(compressed.byteLength);
+  compact.set(compressed);
+  return compact;
+}
+
+export function decompress(value) {
+  return inflateSync(value);
+}
+
+export const nodeCompression = Object.freeze({ encodeUtf8, decodeUtf8, compress, decompress });
+
+export function readHeapUsageRatio() {
+  const stats = getHeapStatistics();
+  const limit = Number(stats.heap_size_limit) || 0;
+  return limit > 0 ? (Number(stats.used_heap_size) || 0) / limit : 0;
+}

package/src/object-hooks.js

@@ -0,0 +1,282 @@
+const OPERATIONS = Object.freeze(["create", "read", "update", "delete"]);
+const OPERATION_SET = new Set(OPERATIONS);
+const META_KEYS = new Set(["enabled", "use", ...OPERATIONS]);
+const EMPTY_CHAIN = Object.freeze([]);
+
+export function createObjectHookRegistry() {
+  return new ObjectHookRegistry();
+}
+
+export function createObjectHookRunner(node, registry = createObjectHookRegistry()) {
+  if (!(registry instanceof ObjectHookRegistry)) {
+    throw new TypeError("objectHooks must be an ObjectHookRegistry");
+  }
+  return new ObjectHookRunner(node, registry);
+}
+
+export function normalizeObjectHooksMeta(value) {
+  if (value === undefined || value === null) return null;
+  if (!isPlainObject(value)) throw new TypeError("collection meta hooks must be a plain object");
+
+  for (const key of Object.keys(value)) {
+    if (!META_KEYS.has(key)) throw new TypeError(`collection meta hooks.${key} is not supported`);
+  }
+  if (value.enabled !== undefined && typeof value.enabled !== "boolean") {
+    throw new TypeError("collection meta hooks.enabled must be a boolean");
+  }
+
+  const out = { enabled: value.enabled !== false };
+  for (const key of ["use", ...OPERATIONS]) {
+    const names = normalizeNames(value[key], `hooks.${key}`);
+    if (names.length) out[key] = names;
+  }
+  return out;
+}
+
+export class ObjectHookRegistry {
+  constructor() {
+    this.definitions = new Map();
+    this.revision = 0;
+  }
+
+  register(name, definition) {
+    const key = normalizeName(name, "hook name");
+    if (this.definitions.has(key)) throw new TypeError(`object hook is already registered: ${key}`);
+
+    const handler = typeof definition === "function" ? definition : definition?.handler;
+    if (typeof handler !== "function") throw new TypeError(`object hook ${key} requires a handler`);
+    const validateMeta = typeof definition === "function" ? null : definition.validateMeta;
+    if (validateMeta != null && typeof validateMeta !== "function") {
+      throw new TypeError(`object hook ${key} validateMeta must be a function`);
+    }
+    const operations = normalizeOperations(typeof definition === "function" ? undefined : definition.operations);
+    this.definitions.set(key, { name: key, handler, operations, validateMeta });
+    this.revision++;
+    return this;
+  }
+
+  get(name) {
+    return this.definitions.get(String(name));
+  }
+
+  get size() {
+    return this.definitions.size;
+  }
+}
+
+export class ObjectHookRunner {
+  constructor(node, registry) {
+    if (!node) throw new TypeError("node is required");
+    this.node = node;
+    this.registry = registry;
+    this.configs = new Map();
+    this.plans = new Map();
+    this.registryRevision = registry.revision;
+    this._loadExistingCollections();
+    this.unsubscribe = node.onChange?.((change) => this._onChange(change)) || null;
+  }
+
+  validateMeta(meta = {}) {
+    const config = normalizeObjectHooksMeta(meta?.hooks);
+    if (!config?.enabled) return config;
+    for (const name of configuredNames(config)) {
+      const hook = this.registry.get(name);
+      if (!hook) throw new TypeError(`object hook is not registered: ${name}`);
+      hook.validateMeta?.(meta);
+    }
+    for (const operation of OPERATIONS) {
+      for (const name of config[operation] || []) {
+        if (!this.registry.get(name)?.operations.has(operation)) {
+          throw new TypeError(`object hook ${name} does not support ${operation}`);
+        }
+      }
+    }
+    return config;
+  }
+
+  run({ operation, variant, database, collection, input, principal = null, batch = null, lookup = null }, execute) {
+    if (!OPERATION_SET.has(operation)) throw new TypeError(`unsupported object hook operation: ${operation}`);
+    if (typeof execute !== "function") throw new TypeError("object hook operation requires an executor");
+
+    const chain = this._plan(database, collection, operation);
+    if (!chain.length) return execute(input, null);
+
+    const context = {
+      operation,
+      variant,
+      database,
+      collection,
+      input,
+      principal: principal ? deepFreeze(structuredClone(principal)) : null,
+      lookup,
+      batch: batch ? Object.freeze({ ...batch }) : null,
+      state: Object.create(null),
+      count: inputCount(input),
+      result: undefined,
+      hooked: true,
+    };
+    let cursor = -1;
+
+    const dispatch = async (index) => {
+      if (index <= cursor) throw hookExecutionError("object hook next() called more than once");
+      cursor = index;
+      if (index === chain.length) {
+        context.result = await execute(context.input, context);
+        return context.result;
+      }
+
+      let called = false;
+      let nextPromise;
+      const next = () => {
+        if (called) throw hookExecutionError(`object hook ${chain[index].name} called next() more than once`);
+        called = true;
+        nextPromise = dispatch(index + 1);
+        return nextPromise;
+      };
+      try {
+        await chain[index].handler(context, next);
+      } catch (err) {
+        if (!err.status) err.status = 500;
+        throw err;
+      }
+      if (!called) throw hookExecutionError(`object hook ${chain[index].name} must call next()`);
+      return nextPromise;
+    };
+
+    return dispatch(0);
+  }
+
+  dispose() {
+    this.unsubscribe?.();
+    this.unsubscribe = null;
+    this.configs.clear();
+    this.plans.clear();
+  }
+
+  _plan(database, collection, operation) {
+    if (!this.registry.size) return EMPTY_CHAIN;
+    if (this.registryRevision !== this.registry.revision) {
+      this.registryRevision = this.registry.revision;
+      this.plans.clear();
+      for (const config of this.configs.values()) this.validateMeta({ hooks: config });
+    }
+
+    const scope = scopeKey(database, collection);
+    const key = `${scope}\0${operation}`;
+    if (this.plans.has(key)) return this.plans.get(key);
+    const config = this.configs.get(scope);
+    if (!config?.enabled) {
+      this.plans.set(key, EMPTY_CHAIN);
+      return EMPTY_CHAIN;
+    }
+
+    const chain = [];
+    for (const name of config.use || []) {
+      const hook = this.registry.get(name);
+      if (!hook) throw hookExecutionError(`object hook is not registered: ${name}`);
+      if (hook.operations.has(operation)) chain.push(hook);
+    }
+    for (const name of config[operation] || []) {
+      const hook = this.registry.get(name);
+      if (!hook) throw hookExecutionError(`object hook is not registered: ${name}`);
+      if (!hook.operations.has(operation)) throw hookExecutionError(`object hook ${name} does not support ${operation}`);
+      if (!chain.includes(hook)) chain.push(hook);
+    }
+    Object.freeze(chain);
+    this.plans.set(key, chain);
+    return chain;
+  }
+
+  _loadExistingCollections() {
+    for (const database of this.node.listDatabases?.() || []) {
+      for (const collection of this.node.listCollections?.(database) || []) {
+        const meta = this.node.getCollectionMeta(database, collection) || {};
+        const config = this.validateMeta(meta);
+        if (config) this.configs.set(scopeKey(database, collection), config);
+      }
+    }
+  }
+
+  _onChange(change = {}) {
+    if (change.kind === "meta") {
+      const key = scopeKey(change.database, change.collection);
+      const config = normalizeObjectHooksMeta(change.meta?.hooks);
+      if (config) this.configs.set(key, config);
+      else this.configs.delete(key);
+      this._invalidateScope(key);
+      return;
+    }
+    if (change.kind === "dropCollection") {
+      const key = scopeKey(change.database, change.collection);
+      this.configs.delete(key);
+      this._invalidateScope(key);
+      return;
+    }
+    if (change.kind === "dropDatabase") {
+      const prefix = `${change.database}\0`;
+      for (const key of this.configs.keys()) if (key.startsWith(prefix)) this.configs.delete(key);
+      for (const key of this.plans.keys()) if (key.startsWith(prefix)) this.plans.delete(key);
+    }
+  }
+
+  _invalidateScope(scope) {
+    for (const operation of OPERATIONS) this.plans.delete(`${scope}\0${operation}`);
+  }
+}
+
+function normalizeOperations(value) {
+  const operations = value === undefined || value === "all" ? OPERATIONS : value;
+  if (!Array.isArray(operations)) throw new TypeError("object hook operations must be an array or 'all'");
+  const normalized = unique(operations.map((operation) => String(operation)));
+  for (const operation of normalized) {
+    if (!OPERATION_SET.has(operation)) throw new TypeError(`unsupported object hook operation: ${operation}`);
+  }
+  return new Set(normalized);
+}
+
+function normalizeNames(value, label) {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) throw new TypeError(`collection meta ${label} must be an array`);
+  return unique(value.map((name) => normalizeName(name, label)));
+}
+
+function normalizeName(value, label) {
+  if (typeof value !== "string" || !value.trim()) throw new TypeError(`${label} must contain non-empty strings`);
+  return value.trim();
+}
+
+function configuredNames(config) {
+  return unique([...(config.use || []), ...OPERATIONS.flatMap((operation) => config[operation] || [])]);
+}
+
+function inputCount(input = {}) {
+  for (const key of ["objects", "patches", "ids"]) {
+    if (Array.isArray(input[key])) return input[key].length;
+  }
+  return 0;
+}
+
+function scopeKey(database, collection) {
+  return `${database}\0${collection}`;
+}
+
+function unique(values) {
+  return [...new Set(values)];
+}
+
+function isPlainObject(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const item of Object.values(value)) deepFreeze(item);
+  return value;
+}
+
+function hookExecutionError(message) {
+  const err = new TypeError(message);
+  err.status = 500;
+  return err;
+}

package/src/object-id.js

@@ -0,0 +1,7 @@
+import { randomBase64Url } from "./runtime.js";
+
+const DEFAULT_BYTES = 12;
+
+export function createObjectId(bytes = DEFAULT_BYTES) {
+  return randomBase64Url(bytes);
+}

package/src/object-storage.js

@@ -0,0 +1,263 @@
+import {
+  CreateBucketCommand,
+  DeleteObjectsCommand,
+  GetObjectCommand,
+  HeadBucketCommand,
+  ListObjectsV2Command,
+  PutObjectCommand,
+  S3Client,
+} from "@aws-sdk/client-s3";
+import { Readable } from "node:stream";
+
+export class MemoryObjectStorage {
+  constructor() {
+    this.objects = new Map();
+  }
+
+  async put(key, body, contentType = "application/json") {
+    this.objects.set(key, {
+      body: typeof body === "string" ? body : JSON.stringify(body),
+      contentType,
+    });
+  }
+
+  async putIfAbsent(key, body, contentType = "application/json") {
+    if (this.objects.has(key)) return false;
+    await this.put(key, body, contentType);
+    return true;
+  }
+
+  async putBlob(key, body, contentType = "application/octet-stream") {
+    this.objects.set(key, {
+      body: Buffer.isBuffer(body) ? Buffer.from(body) : Buffer.from(body || ""),
+      contentType,
+    });
+  }
+
+  async get(key) {
+    return this.objects.get(key)?.body ?? null;
+  }
+
+  async getStream(key) {
+    const body = this.objects.get(key)?.body;
+    return body === undefined ? null : Readable.from([body]);
+  }
+
+  async getBlob(key) {
+    const object = this.objects.get(key);
+    if (!object) return null;
+    const body = Buffer.isBuffer(object.body) ? Buffer.from(object.body) : Buffer.from(String(object.body));
+    return {
+      body,
+      contentType: object.contentType || "application/octet-stream",
+      contentLength: body.length,
+    };
+  }
+
+  async list(prefix = "") {
+    return [...this.objects.keys()].filter((key) => key.startsWith(prefix)).sort();
+  }
+
+  async delete(keys) {
+    let count = 0;
+    for (const key of keys) {
+      if (this.objects.delete(key)) count++;
+    }
+    return count;
+  }
+
+  async deletePrefix(prefix) {
+    let count = 0;
+    for (const key of [...this.objects.keys()]) {
+      if (!key.startsWith(prefix)) continue;
+      this.objects.delete(key);
+      count++;
+    }
+    return count;
+  }
+}
+
+export class S3ObjectStorage {
+  constructor({
+    bucket,
+    endpoint,
+    region = "us-east-1",
+    accessKeyId,
+    secretAccessKey,
+    forcePathStyle,
+  } = {}) {
+    if (!bucket) throw new Error("S3 bucket is required");
+    this.bucket = bucket;
+    this.region = region;
+    this.ready = false;
+    this.client = new S3Client({
+      region,
+      ...(endpoint ? { endpoint, forcePathStyle: forcePathStyle ?? true } : {}),
+      ...(accessKeyId && secretAccessKey
+        ? { credentials: { accessKeyId, secretAccessKey } }
+        : {}),
+    });
+  }
+
+  async ensureBucket() {
+    if (this.ready) return;
+    try {
+      await this.client.send(new HeadBucketCommand({ Bucket: this.bucket }));
+    } catch (err) {
+      const code = err.$metadata?.httpStatusCode;
+      if (code !== 404 && err.name !== "NotFound" && err.name !== "NoSuchBucket") throw err;
+      await this.client.send(new CreateBucketCommand({
+        Bucket: this.bucket,
+        ...createBucketLocation(this.region),
+      }));
+    }
+    this.ready = true;
+  }
+
+  async put(key, body, contentType = "application/json") {
+    await this.ensureBucket();
+    await this.client.send(new PutObjectCommand({
+      Bucket: this.bucket,
+      Key: key,
+      Body: typeof body === "string" ? body : JSON.stringify(body),
+      ContentType: contentType,
+    }));
+  }
+
+  async putIfAbsent(key, body, contentType = "application/json") {
+    await this.ensureBucket();
+    try {
+      await this.client.send(new PutObjectCommand({
+        Bucket: this.bucket,
+        Key: key,
+        Body: typeof body === "string" ? body : JSON.stringify(body),
+        ContentType: contentType,
+        IfNoneMatch: "*",
+      }));
+      return true;
+    } catch (err) {
+      const status = err.$metadata?.httpStatusCode;
+      if (status === 409 || status === 412 || err.name === "PreconditionFailed") return false;
+      throw err;
+    }
+  }
+
+  async putBlob(key, body, contentType = "application/octet-stream") {
+    await this.ensureBucket();
+    await this.client.send(new PutObjectCommand({
+      Bucket: this.bucket,
+      Key: key,
+      Body: body,
+      ContentType: contentType,
+    }));
+  }
+
+  async get(key) {
+    await this.ensureBucket();
+    try {
+      const got = await this.client.send(new GetObjectCommand({
+        Bucket: this.bucket,
+        Key: key,
+      }));
+      return bodyToString(got.Body);
+    } catch (err) {
+      const code = err.$metadata?.httpStatusCode;
+      if (code === 404 || err.name === "NoSuchKey" || err.name === "NotFound") return null;
+      throw err;
+    }
+  }
+
+  async getStream(key) {
+    await this.ensureBucket();
+    try {
+      const got = await this.client.send(new GetObjectCommand({
+        Bucket: this.bucket,
+        Key: key,
+      }));
+      return got.Body || null;
+    } catch (err) {
+      const code = err.$metadata?.httpStatusCode;
+      if (code === 404 || err.name === "NoSuchKey" || err.name === "NotFound") return null;
+      throw err;
+    }
+  }
+
+  async getBlob(key) {
+    await this.ensureBucket();
+    try {
+      const got = await this.client.send(new GetObjectCommand({
+        Bucket: this.bucket,
+        Key: key,
+      }));
+      return {
+        body: got.Body,
+        contentType: got.ContentType || "application/octet-stream",
+        contentLength: got.ContentLength,
+      };
+    } catch (err) {
+      const code = err.$metadata?.httpStatusCode;
+      if (code === 404 || err.name === "NoSuchKey" || err.name === "NotFound") return null;
+      throw err;
+    }
+  }
+
+  async list(prefix = "") {
+    await this.ensureBucket();
+    const keys = [];
+    let ContinuationToken;
+    do {
+      const res = await this.client.send(new ListObjectsV2Command({
+        Bucket: this.bucket,
+        Prefix: prefix,
+        ContinuationToken,
+      }));
+      for (const item of res.Contents || []) if (item.Key) keys.push(item.Key);
+      ContinuationToken = res.IsTruncated ? res.NextContinuationToken : undefined;
+    } while (ContinuationToken);
+    return keys.sort();
+  }
+
+  async delete(keys) {
+    await this.ensureBucket();
+    let count = 0;
+    for (let i = 0; i < keys.length; i += 1000) {
+      const chunk = keys.slice(i, i + 1000);
+      if (!chunk.length) continue;
+      await this.client.send(new DeleteObjectsCommand({
+        Bucket: this.bucket,
+        Delete: { Objects: chunk.map((Key) => ({ Key })), Quiet: true },
+      }));
+      count += chunk.length;
+    }
+    return count;
+  }
+
+  async deletePrefix(prefix) {
+    const keys = await this.list(prefix);
+    return this.delete(keys);
+  }
+}
+
+export function createObjectStorage({ mode = "off", s3 = {} } = {}) {
+  if (mode === "memory") return new MemoryObjectStorage();
+  if (mode === "s3") return new S3ObjectStorage(s3);
+  if (mode === "off" || mode === false) return null;
+  throw new Error(`unsupported object storage mode: ${mode}`);
+}
+
+function createBucketLocation(region) {
+  if (!region || region === "us-east-1") return {};
+  return {
+    CreateBucketConfiguration: {
+      LocationConstraint: region,
+    },
+  };
+}
+
+async function bodyToString(body) {
+  if (!body) return "";
+  if (typeof body.transformToString === "function") return body.transformToString();
+  const chunks = [];
+  for await (const chunk of body) chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks).toString("utf8");
+}