procmesh-js 0.1.0

package/src/protocol.js

@@ -0,0 +1,169 @@
+'use strict';
+
+const EventEmitter = require('events');
+
+const PROTOCOL_VERSION = 2;
+
+/** Message type tags. Kept short to minimize JSON overhead. */
+const TYPES = {
+  // connection / control
+  HELLO: 'hello',
+  WELCOME: 'welcome',
+  PING: 'ping',
+  PONG: 'pong',
+  OK: 'ok',
+  ERR: 'err',
+  SHUTDOWN: 'shutdown',
+  STATS: 'stats',
+  // cache
+  GET: 'get',
+  SET: 'set',
+  DEL: 'del',
+  HAS: 'has',
+  KEYS: 'keys',
+  CLEAR: 'clear',
+  MGET: 'mget',
+  MSET: 'mset',
+  // atomic
+  INCR: 'incr',
+  DECR: 'decr',
+  CAS: 'cas',
+  // locks
+  LOCK: 'lock',
+  UNLOCK: 'unlock',
+  // fenced mutations (guarded by a lock's fencing token)
+  FSET: 'fset',
+  FCAS: 'fcas',
+  FDEL: 'fdel',
+  // pub/sub
+  SUBSCRIBE: 'sub',
+  UNSUBSCRIBE: 'unsub',
+  PUBLISH: 'pub',
+  MESSAGE: 'msg',
+  // rpc
+  REGISTER: 'reg',
+  UNREGISTER: 'unreg',
+  CALL: 'call',
+  INVOKE: 'invoke',
+  RESULT: 'result',
+};
+
+const DEFAULT_MAX_FRAME = 64 * 1024 * 1024; // 64 MiB
+const DEFAULT_SEND_HWM = 16 * 1024 * 1024; // 16 MiB: soft cap, droppable frames dropped beyond this
+const DEFAULT_SEND_HARD_LIMIT = 64 * 1024 * 1024; // 64 MiB: hard cap, slow consumer is disconnected
+
+/**
+ * Topic match. A subscription ending in `*` matches by prefix (everything before
+ * the `*`); otherwise it must match the channel exactly. Predictable and cheap —
+ * no regex. e.g. `matchTopic('orders.*', 'orders.created') === true`.
+ */
+function matchTopic(pattern, channel) {
+  if (pattern === channel) return true;
+  if (pattern.endsWith('*')) return channel.startsWith(pattern.slice(0, -1));
+  return false;
+}
+
+/** Whether a subscription string is a wildcard pattern rather than an exact channel. */
+function isPattern(sub) {
+  return typeof sub === 'string' && sub.endsWith('*');
+}
+
+/** Encode an object as a length-prefixed frame: [uint32 BE length][payload]. */
+function encodeFrame(codec, obj) {
+  const payload = codec.encode(obj);
+  const frame = Buffer.allocUnsafe(4 + payload.length);
+  frame.writeUInt32BE(payload.length, 0);
+  payload.copy(frame, 4);
+  return frame;
+}
+
+/** Incremental decoder that buffers partial reads and yields complete frames. */
+class FrameDecoder {
+  constructor(codec, { maxFrameSize = DEFAULT_MAX_FRAME } = {}) {
+    this.codec = codec;
+    this.maxFrameSize = maxFrameSize;
+    this.buffer = Buffer.alloc(0);
+  }
+
+  push(chunk, onMessage) {
+    this.buffer = this.buffer.length ? Buffer.concat([this.buffer, chunk]) : chunk;
+    for (;;) {
+      if (this.buffer.length < 4) return;
+      const len = this.buffer.readUInt32BE(0);
+      if (len > this.maxFrameSize) {
+        throw new Error(`frame too large: ${len} > ${this.maxFrameSize}`);
+      }
+      if (this.buffer.length < 4 + len) return;
+      const payload = this.buffer.subarray(4, 4 + len);
+      const obj = this.codec.decode(payload);
+      this.buffer = this.buffer.subarray(4 + len);
+      onMessage(obj);
+    }
+  }
+}
+
+/**
+ * Wraps a duplex socket with framed message send/receive. Both the client and
+ * the broker use this so framing lives in exactly one place.
+ *
+ * Emits: 'message' (obj), 'close', 'error' (err).
+ */
+class Peer extends EventEmitter {
+  constructor(socket, codec, opts = {}) {
+    super();
+    this.socket = socket;
+    this.codec = codec;
+    this.decoder = new FrameDecoder(codec, opts);
+    this.sendHighWaterMark = opts.sendHighWaterMark || DEFAULT_SEND_HWM;
+    this.sendHardLimit = opts.sendHardLimit || DEFAULT_SEND_HARD_LIMIT;
+    socket.on('data', (chunk) => {
+      try {
+        this.decoder.push(chunk, (msg) => this.emit('message', msg));
+      } catch (err) {
+        this.emit('error', err);
+        socket.destroy(err);
+      }
+    });
+    socket.on('error', (err) => this.emit('error', err));
+    socket.on('close', () => this.emit('close'));
+  }
+
+  /**
+   * Send a framed message, applying High-Water-Mark backpressure.
+   *
+   * - `droppable: true` (e.g. pub/sub fan-out): if the socket's outbound buffer
+   *   already exceeds the soft HWM, the frame is DROPPED (returns 'dropped') so a
+   *   slow consumer can't make us buffer without bound. Favors liveness.
+   * - otherwise (replies/RPC): if the buffer exceeds the hard limit, the slow
+   *   consumer is DISCONNECTED ('overflow') to protect the broker; below that it
+   *   writes normally and returns socket.write()'s drain boolean.
+   *
+   * @returns {boolean|'dropped'|'overflow'}
+   */
+  send(obj, { droppable = false } = {}) {
+    if (this.socket.destroyed) return false;
+    const queued = this.socket.writableLength;
+    if (droppable && queued > this.sendHighWaterMark) {
+      return 'dropped';
+    }
+    if (!droppable && queued > this.sendHardLimit) {
+      this.socket.destroy(new Error('send buffer overflow (slow consumer)'));
+      return 'overflow';
+    }
+    return this.socket.write(encodeFrame(this.codec, obj));
+  }
+
+  destroy() {
+    this.socket.destroy();
+  }
+}
+
+module.exports = {
+  PROTOCOL_VERSION,
+  TYPES,
+  encodeFrame,
+  FrameDecoder,
+  Peer,
+  matchTopic,
+  isPattern,
+};

package/src/sharded-client.js

@@ -0,0 +1,338 @@
+'use strict';
+
+const EventEmitter = require('events');
+const Client = require('./client');
+const { resolveAddress } = require('./transport');
+const { isPattern } = require('./protocol');
+const { shardIndex } = require('./hashring');
+
+/**
+ * A client handle that spreads work across N broker processes (N cores), exposing the
+ * exact same API as {@link Client} so callers never branch. It composes N plain Clients
+ * — one per shard broker — and routes each operation to the shard that owns it:
+ *
+ *   - cache / atomic (get/set/incr/cas/…)  → hash(key)
+ *   - locks + fenced mutations             → hash(lockKey)
+ *   - RPC (register/call)                  → hash(procName)
+ *   - pub/sub publish + exact subscribe    → hash(channel)
+ *   - pub/sub wildcard subscribe           → ALL shards (so it catches a publish on any shard)
+ *
+ * Because each key/name/channel hashes to exactly one broker, atomic ops and locks stay
+ * correct by construction — the same way a single broker is. All reconnect, replay, and
+ * delivery logic lives in the child Clients; this class is a thin router + event aggregator.
+ *
+ * INVARIANT: every process joining the same logical mesh MUST use the same shard count and
+ * the same per-shard naming/addresses, or a given key will hash to different brokers across
+ * processes (writer/reader split-brain).
+ *
+ * Emits: 'connect' (all shards up), 'disconnect' (all shards down), 'error' (err.shard = i),
+ * and the additive per-shard events 'shard-reconnect' (i) / 'shard-disconnect' (i).
+ */
+class ShardedClient extends EventEmitter {
+  constructor(opts = {}) {
+    super();
+    this.opts = opts;
+    this.name = opts.name || 'default';
+    this.closed = false;
+    this._allUp = false;
+
+    const specs = resolveShardSpecs(opts, this.name);
+    this.n = specs.length;
+    if (this.n < 1) throw new TypeError('shards must resolve to >= 1 shard');
+
+    // resolveAddress short-circuits to PROCMESH_SOCKET for every name, which would collapse
+    // all shards onto one socket. Distinct addresses are required for sharding to mean anything.
+    const addrs = specs.map((s) => s.address);
+    if (new Set(addrs).size !== this.n) {
+      throw new Error('sharded client requires a distinct address per shard (is PROCMESH_SOCKET set?)');
+    }
+
+    this.clients = specs.map((spec, i) => {
+      const child = new Client({ ...opts, shards: undefined, name: spec.name, address: spec.address });
+      this._wireChild(child, i);
+      return child;
+    });
+  }
+
+  // ----------------------------------------------------------------- routing helpers
+
+  _clientForKey(key) {
+    return this.clients[shardIndex(key, this.n)];
+  }
+
+  _clientForChannel(channel) {
+    return this.clients[shardIndex(channel, this.n)];
+  }
+
+  _clientForProc(name) {
+    return this.clients[shardIndex(name, this.n)];
+  }
+
+  _fanOut(fn) {
+    return Promise.all(this.clients.map(fn));
+  }
+
+  // ----------------------------------------------------------------------- events
+
+  _wireChild(child, i) {
+    child.on('error', (err) => {
+      if (err && typeof err === 'object') err.shard = i;
+      this.emit('error', err);
+    });
+    child.on('connect', () => this._onChildState());
+    child.on('reconnect', () => {
+      this.emit('shard-reconnect', i);
+      this._onChildState();
+    });
+    child.on('disconnect', () => {
+      this.emit('shard-disconnect', i);
+      if (this.clients.every((c) => !c.connected)) this.emit('disconnect');
+    });
+  }
+
+  /** Edge-trigger the mesh-level 'connect' once every shard is connected. */
+  _onChildState() {
+    const allUp = this.clients.every((c) => c.connected);
+    if (allUp && !this._allUp) this.emit('connect');
+    this._allUp = allUp;
+  }
+
+  // -------------------------------------------------------------------- connection
+
+  async connect() {
+    // Fail-fast: a half-connected mesh would silently drop a slice of the keyspace.
+    await this._fanOut((c) => c.connect());
+    this._allUp = true;
+    return this;
+  }
+
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    await this._fanOut((c) => c.close());
+  }
+
+  // --------------------------------------------------------------------- cache
+
+  get(key) {
+    return this._clientForKey(key).get(key);
+  }
+
+  set(key, value, opts = {}) {
+    return this._clientForKey(key).set(key, value, opts);
+  }
+
+  del(key) {
+    return this._clientForKey(key).del(key);
+  }
+
+  has(key) {
+    return this._clientForKey(key).has(key);
+  }
+
+  async keys() {
+    const lists = await this._fanOut((c) => c.keys());
+    return [].concat(...lists);
+  }
+
+  async clear() {
+    await this._fanOut((c) => c.clear());
+  }
+
+  /** Split keys per shard, fan out, recombine aligned to input order (undefined for misses). */
+  async mget(keys) {
+    const buckets = this.clients.map(() => []);
+    keys.forEach((key, idx) => buckets[shardIndex(key, this.n)].push({ key, idx }));
+    const out = new Array(keys.length);
+    await Promise.all(
+      buckets.map(async (bucket, s) => {
+        if (!bucket.length) return;
+        const values = await this.clients[s].mget(bucket.map((x) => x.key));
+        bucket.forEach((x, j) => {
+          out[x.idx] = values[j];
+        });
+      })
+    );
+    return out;
+  }
+
+  /** Group entries per shard, fan out the writes. */
+  async mset(entries) {
+    const list = Array.isArray(entries) ? entries : Object.entries(entries);
+    const buckets = this.clients.map(() => []);
+    for (const entry of list) buckets[shardIndex(entry[0], this.n)].push(entry);
+    await Promise.all(buckets.map((bucket, s) => (bucket.length ? this.clients[s].mset(bucket) : null)));
+  }
+
+  // -------------------------------------------------------------------- atomic
+
+  incr(key, by = 1) {
+    return this._clientForKey(key).incr(key, by);
+  }
+
+  decr(key, by = 1) {
+    return this._clientForKey(key).decr(key, by);
+  }
+
+  cas(key, prev, next) {
+    return this._clientForKey(key).cas(key, prev, next);
+  }
+
+  // -------------------------------------------------------------------- pub/sub
+
+  /**
+   * Exact channels subscribe on the channel's owning shard; wildcard patterns subscribe
+   * on EVERY shard (a publish can land on any of them). The returned off() mirrors the
+   * subscription's footprint.
+   */
+  async subscribe(channel, handler) {
+    if (!isPattern(channel)) return this._clientForChannel(channel).subscribe(channel, handler);
+    const offs = await this._fanOut((c) => c.subscribe(channel, handler));
+    return async () => {
+      await Promise.all(offs.map((off) => off()));
+    };
+  }
+
+  unsubscribe(channel, handler) {
+    if (!isPattern(channel)) return this._clientForChannel(channel).unsubscribe(channel, handler);
+    return this._fanOut((c) => c.unsubscribe(channel, handler));
+  }
+
+  /**
+   * Publish to exactly ONE broker (the channel's owning shard). Exact subscribers hash to
+   * that same shard and wildcard subscribers are present on every shard, so every matching
+   * subscriber is reachable there — and a message can never be delivered twice. The returned
+   * `delivered` count is that broker's matching-subscriber count (which is all of them).
+   */
+  publish(channel, payload) {
+    return this._clientForChannel(channel).publish(channel, payload);
+  }
+
+  // ------------------------------------------------------------------------ rpc
+
+  register(name, fn) {
+    return this._clientForProc(name).register(name, fn);
+  }
+
+  unregister(name) {
+    return this._clientForProc(name).unregister(name);
+  }
+
+  call(name, args = [], opts = {}) {
+    return this._clientForProc(name).call(name, args, opts);
+  }
+
+  // ---------------------------------------------------------------------- locks
+
+  /**
+   * Locks and their fenced mutations route by the LOCK key, so a lock and every fenced write
+   * guarded by it share one broker (the fencing counter is per-broker). NOTE: this means a
+   * fenced write to data key `k` lands on the lock's shard, not shardIndex(k) — keep the lock
+   * key and guarded data keys colocated (use the same string, or namespace data under the lock).
+   */
+  lock(key, opts = {}) {
+    return this._clientForKey(key).lock(key, opts);
+  }
+
+  withLock(key, fn, opts = {}) {
+    return this._clientForKey(key).withLock(key, fn, opts);
+  }
+
+  // ------------------------------------------------------- fenced mutations (lock-guarded)
+
+  fencedSet(lockKey, token, key, value, opts = {}) {
+    return this._clientForKey(lockKey).fencedSet(lockKey, token, key, value, opts);
+  }
+
+  fencedCas(lockKey, token, key, prev, next) {
+    return this._clientForKey(lockKey).fencedCas(lockKey, token, key, prev, next);
+  }
+
+  fencedDel(lockKey, token, key) {
+    return this._clientForKey(lockKey).fencedDel(lockKey, token, key);
+  }
+
+  // ---------------------------------------------------------------- misc / admin
+
+  /** True only if every shard answered its ping. */
+  async ping() {
+    const replies = await this._fanOut((c) => c.ping());
+    return replies.every(Boolean);
+  }
+
+  /** Aggregated snapshot across all shards, with a per-shard `shards` array for drill-down. */
+  async stats() {
+    const per = await this._fanOut((c) => c.stats());
+    return aggregateStats(per);
+  }
+
+  /** Ask every shard broker to shut down (best-effort). */
+  async shutdownBroker() {
+    await this._fanOut((c) => c.shutdownBroker().catch(() => {}));
+  }
+}
+
+/**
+ * Resolve opts.shards to an array of { name, address } specs.
+ * - number N            → name#0 .. name#(N-1), each address derived from resolveAddress.
+ * - Array<string>       → each string is a NAME (resolved via resolveAddress).
+ * - Array<{name|address}> → {address} used verbatim; {name} resolved.
+ */
+function resolveShardSpecs(opts, baseName) {
+  const { shards } = opts;
+  if (typeof shards === 'number') {
+    const specs = [];
+    for (let i = 0; i < shards; i++) {
+      const name = `${baseName}#${i}`;
+      specs.push({ name, address: resolveAddress(name) });
+    }
+    return specs;
+  }
+  if (Array.isArray(shards)) {
+    return shards.map((s) => {
+      if (typeof s === 'string') return { name: s, address: resolveAddress(s) };
+      if (s && typeof s === 'object') {
+        if (s.address) return { name: s.name, address: s.address };
+        if (s.name) return { name: s.name, address: resolveAddress(s.name) };
+      }
+      throw new TypeError('each shard spec must be a name string or { name } / { address }');
+    });
+  }
+  throw new TypeError('opts.shards must be a number or an array of names/specs');
+}
+
+/** Merge per-shard snapshots into one mesh-level snapshot (superset of Broker.snapshot()). */
+function aggregateStats(per) {
+  const sum = (field) => per.reduce((acc, s) => acc + (s[field] || 0), 0);
+  const memField = (field) => per.reduce((acc, s) => acc + (s.memory ? s.memory[field] || 0 : 0), 0);
+  const ops = {};
+  for (const s of per) {
+    for (const [k, v] of Object.entries(s.ops || {})) ops[k] = (ops[k] || 0) + v;
+  }
+  return {
+    shardCount: per.length,
+    shards: per,
+    uptimeMs: per.reduce((m, s) => Math.max(m, s.uptimeMs || 0), 0),
+    connections: sum('connections'),
+    cacheSize: sum('cacheSize'),
+    ops,
+    dropped: sum('dropped'),
+    reaped: sum('reaped'),
+    locks: sum('locks'),
+    lockWaiters: sum('lockWaiters'),
+    pendingCalls: sum('pendingCalls'),
+    // Over-counts wildcard subscriptions (present on every shard) — documented.
+    subscriptions: sum('subscriptions'),
+    procs: [].concat(...per.map((s) => s.procs || [])),
+    // SUM across brokers — can exceed 1.0, which is the whole point of sharding.
+    cpuCoreFraction: per.reduce((acc, s) => acc + (s.cpuCoreFraction || 0), 0),
+    memory: {
+      rss: memField('rss'),
+      heapTotal: memField('heapTotal'),
+      heapUsed: memField('heapUsed'),
+      external: memField('external'),
+    },
+  };
+}
+
+module.exports = ShardedClient;

package/src/store.js

@@ -0,0 +1,155 @@
+'use strict';
+
+const { LRUCache } = require('lru-cache');
+
+/** Structural equality via canonical JSON; undefined is treated as "absent" (null). */
+function eq(a, b) {
+  return JSON.stringify(a === undefined ? null : a) === JSON.stringify(b === undefined ? null : b);
+}
+
+/** Rough byte size of a value, for optional maxSize-based eviction. */
+function approxSize(value) {
+  try {
+    return Buffer.byteLength(JSON.stringify(value) || '') + 1;
+  } catch {
+    return 1;
+  }
+}
+
+/**
+ * The authoritative key-value store, held in the broker process only.
+ * Wraps lru-cache for size/TTL-based eviction. All mutations run on the broker's
+ * single event loop, so atomic ops (incr/decr/cas) need no internal locking.
+ */
+class Store {
+  constructor({ max = 10000, ttl = 0, maxSize = 0 } = {}) {
+    const opts = {};
+    // lru-cache requires at least one bound. We always set `max` unless a byte
+    // budget is given. Per-item TTLs work as long as the ttl feature is enabled,
+    // so we enable it with `ttl: 0` (no default expiry) when no global ttl is set.
+    if (maxSize > 0) {
+      opts.maxSize = maxSize;
+      opts.sizeCalculation = approxSize;
+    } else {
+      opts.max = max;
+    }
+    opts.ttl = ttl > 0 ? ttl : 0;
+    opts.ttlAutopurge = ttl > 0; // proactively purge expired entries when a default ttl exists
+    opts.allowStale = false;
+    this.cache = new LRUCache(opts);
+  }
+
+  get(key) {
+    return this.cache.get(key);
+  }
+
+  set(key, value, ttl) {
+    const opts = ttl && ttl > 0 ? { ttl } : undefined;
+    this.cache.set(key, value, opts);
+    return true;
+  }
+
+  del(key) {
+    return this.cache.delete(key);
+  }
+
+  has(key) {
+    return this.cache.has(key);
+  }
+
+  keys() {
+    return [...this.cache.keys()];
+  }
+
+  clear() {
+    this.cache.clear();
+    return true;
+  }
+
+  /**
+   * Bulk get. Returns { values, found } so callers can distinguish a missing key
+   * from a stored `null`/`undefined` even across a JSON boundary (which would
+   * otherwise collapse array holes to null).
+   */
+  mget(keys) {
+    const values = [];
+    const found = [];
+    for (const k of keys) {
+      const hit = this.cache.has(k);
+      found.push(hit);
+      values.push(hit ? this.cache.get(k) : null);
+    }
+    return { values, found };
+  }
+
+  mset(entries) {
+    for (const [k, v] of entries) this.cache.set(k, v);
+    return true;
+  }
+
+  incr(key, by = 1) {
+    const cur = this.cache.get(key);
+    const base = cur === undefined ? 0 : cur;
+    if (typeof base !== 'number') {
+      const err = new Error(`value at "${key}" is not a number`);
+      err.code = 'ENOTNUMBER';
+      throw err;
+    }
+    const next = base + by;
+    // Read-modify-write must not reset an existing per-item TTL: a counter created with an
+    // expiry keeps counting down rather than becoming immortal on the next incr.
+    this.cache.set(key, next, { noUpdateTTL: true });
+    return next;
+  }
+
+  /** Compare-and-set. Sets to `next` only if current value equals `prev`. */
+  cas(key, prev, next) {
+    const cur = this.cache.get(key);
+    if (!eq(cur, prev)) return false;
+    if (next === undefined) this.cache.delete(key);
+    else this.cache.set(key, next, { noUpdateTTL: true }); // in-place update preserves any TTL
+    return true;
+  }
+
+  get size() {
+    return this.cache.size;
+  }
+
+  /**
+   * Remaining lifetime of `key` in ms, or 0 for "no expiry" (and for a missing/expired key).
+   * Used to mirror the live TTL into the persistence log after an atomic op.
+   */
+  remainingTTL(key) {
+    const r = this.cache.getRemainingTTL(key);
+    return r === Infinity ? 0 : Math.max(0, r);
+  }
+
+  /**
+   * Snapshot every live entry as `{ k, v, e }` where `e` is an ABSOLUTE expiry timestamp
+   * (ms epoch), or 0 for no expiry. Absolute (not remaining) so a reload after delay restores
+   * the correct lifetime. Expired entries are skipped.
+   */
+  dump() {
+    const now = Date.now();
+    const entries = [];
+    for (const key of this.cache.keys()) {
+      const remaining = this.cache.getRemainingTTL(key);
+      if (remaining <= 0) continue; // expired (0) — drop it
+      const value = this.cache.peek(key); // no recency churn during a dump
+      entries.push({ k: key, v: value, e: remaining === Infinity ? 0 : now + remaining });
+    }
+    return entries;
+  }
+
+  /** Restore entries produced by `dump()` (or individual persisted set records). */
+  load(entries) {
+    const now = Date.now();
+    for (const { k, v, e } of entries) {
+      if (e && e <= now) continue; // already expired
+      const ttl = e ? e - now : undefined;
+      this.cache.set(k, v, ttl ? { ttl } : undefined);
+    }
+  }
+}
+
+module.exports = Store;

package/src/transport.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const os = require('os');
+const path = require('path');
+
+/**
+ * Resolve the local socket address for a given broker name.
+ *
+ * On Windows we must use a named pipe (`\\.\pipe\<name>`); on POSIX systems we
+ * use a Unix domain socket file under the OS temp dir. Node's `net` module
+ * accepts both forms transparently as the `path` argument to listen()/connect().
+ *
+ * Precedence: explicit env override (PROCMESH_SOCKET) > derived from name.
+ */
+function resolveAddress(name = 'default') {
+  if (process.env.PROCMESH_SOCKET) return process.env.PROCMESH_SOCKET;
+  const id = `procmesh-${name}`;
+  if (process.platform === 'win32') {
+    return `\\\\.\\pipe\\${id}`;
+  }
+  return path.join(os.tmpdir(), `${id}.sock`);
+}
+
+/** True if the address is a Windows named pipe (no filesystem entry to clean up). */
+function isPipe(address) {
+  return (
+    typeof address === 'string' &&
+    (address.startsWith('\\\\.\\pipe\\') || address.startsWith('\\\\?\\pipe\\'))
+  );
+}
+
+module.exports = { resolveAddress, isPipe };