@dcl/protocol 1.0.0-2907820380.commit-4e0eac3 → 1.0.0-29255960851.commit-cd43ffd

package/protoc-gen-bitwise/generator_csharp.js

@@ -0,0 +1,248 @@
+'use strict'
+
+/**
+ * C# code generator for the protoc-gen-bitwise plugin.
+ *
+ * For every proto message that contains at least one uint32 field annotated
+ * with [(quantized)], this module emits a C# partial class that adds a computed
+ * float property named {FieldName}Quantized. The getter decodes the stored
+ * uint32 to a float; the setter encodes a float back to a uint32. Standard
+ * protobuf handles serialization of the uint32 wire field; this class adds a
+ * typed float accessor on top.
+ *
+ * Only uint32 fields are supported. bit_packed and unannotated fields are
+ * passed through without generating any accessor.
+ *
+ * Port of the original generator_csharp.py — output is intended to be
+ * byte-for-byte identical.
+ */
+
+const { getFieldOptions } = require('./options')
+
+// FieldDescriptorProto type/label constants.
+const TYPE_UINT32 = 13
+const LABEL_REPEATED = 3
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Mirrors Python str.capitalize(): upper-first, lowercase the rest. */
+function capitalize(word) {
+  if (word.length === 0) return ''
+  return word[0].toUpperCase() + word.slice(1).toLowerCase()
+}
+
+/** position_x -> PositionX */
+function snakeToPascal(name) {
+  return name.split('_').map(capitalize).join('')
+}
+
+/** decentraland.kernel.comms.v3 -> Decentraland.Kernel.Comms.V3 */
+function packageToNamespace(pkg) {
+  if (!pkg) return 'Generated'
+  return pkg.split('.').map(capitalize).join('.')
+}
+
+/**
+ * Format a number with C printf %g semantics at `precision` significant digits:
+ * shortest of fixed/scientific, with trailing zeros and a trailing dot removed.
+ * Reproduces Python's `f'{value:.{precision}g}'`.
+ */
+function formatG(value, precision) {
+  if (precision <= 0) precision = 1
+  if (value === 0) return '0'
+  if (!Number.isFinite(value)) return value > 0 ? 'inf' : 'nan'
+
+  const negative = value < 0
+  const v = Math.abs(value)
+
+  // Correctly-rounded scientific form yields the decimal exponent X (handling
+  // carry such as 9.999 -> 1.0e+1).
+  const sci = v.toExponential(precision - 1)
+  const eIdx = sci.indexOf('e')
+  const X = parseInt(sci.slice(eIdx + 1), 10)
+
+  let result
+  if (X >= -4 && X < precision) {
+    // Fixed notation with (precision - 1 - X) fraction digits.
+    const fractionDigits = precision - 1 - X
+    result = v.toFixed(fractionDigits >= 0 ? fractionDigits : 0)
+    if (result.indexOf('.') !== -1) {
+      result = result.replace(/0+$/, '').replace(/\.$/, '')
+    }
+  } else {
+    // Scientific notation; printf prints at least two exponent digits.
+    let mantissa = sci.slice(0, eIdx)
+    if (mantissa.indexOf('.') !== -1) {
+      mantissa = mantissa.replace(/0+$/, '').replace(/\.$/, '')
+    }
+    const expSign = X < 0 ? '-' : '+'
+    let expDigits = String(Math.abs(X))
+    if (expDigits.length < 2) expDigits = '0' + expDigits
+    result = mantissa + 'e' + expSign + expDigits
+  }
+
+  return (negative ? '-' : '') + result
+}
+
+/** Format a value as a C# float literal (e.g. -100.0f). */
+function formatFloat(value) {
+  let text = formatG(value, 8)
+  if (text.indexOf('.') === -1 && text.indexOf('e') === -1 && text.indexOf('E') === -1) {
+    text += '.0'
+  }
+  return text + 'f'
+}
+
+/** Format a quantization step size for a doc comment (e.g. "≈ 0.003"). */
+function formatStep(step) {
+  return '≈ ' + formatG(step, 6)
+}
+
+// ---------------------------------------------------------------------------
+// Per-message code generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a C# partial class for a proto message, or null if it has no
+ * quantized uint32 fields. Returns an array of lines (no trailing newline).
+ */
+function generateMessage(msgProto, indent) {
+  const i = indent || '    '
+  const props = []
+
+  for (const field of msgProto.field) {
+    // Repeated/map fields are not supported.
+    if (field.label === LABEL_REPEATED) continue
+    // Only uint32 fields are candidates for quantized accessors.
+    if (field.type !== TYPE_UINT32) continue
+
+    const { quantized, quantizedPower } = getFieldOptions(field.optionsRaw)
+    const propName = snakeToPascal(field.name)
+
+    let doc, getExpr, setExpr, step, bits
+    if (quantized !== null) {
+      const mn = formatFloat(quantized.min)
+      const mx = formatFloat(quantized.max)
+      bits = quantized.bits
+      // Uniform quantizer — the step is constant across the whole range.
+      step = (quantized.max - quantized.min) / ((1 << bits) - 1)
+      doc = `Range [${mn}, ${mx}], ${bits} bits, step ${formatStep(step)}.`
+      getExpr = `Quantize.Decode(${propName}, ${mn}, ${mx}, ${bits})`
+      setExpr = `Quantize.Encode(value, ${mn}, ${mx}, ${bits})`
+    } else if (quantizedPower !== null) {
+      const mx = formatFloat(quantizedPower.max)
+      const pw = formatFloat(quantizedPower.pow)
+      bits = quantizedPower.bits
+      // Power curve is non-uniform: the finest step sits next to zero (first magnitude code),
+      // the COARSEST at the top of the range. The coarsest step upper-bounds the error for any
+      // value, so that's what the exposed {Name}QuantizedStep const carries (safe as a tolerance).
+      const magSteps = (1 << (bits - 1)) - 1
+      const nearZeroStep = quantizedPower.max * Math.pow(1 / magSteps, quantizedPower.pow)
+      step = quantizedPower.max * (1 - Math.pow((magSteps - 1) / magSteps, quantizedPower.pow))
+      doc =
+        `Range [-${mx}, ${mx}], power ${pw}, ${bits} bits ` +
+        `(sign + ${bits - 1}-bit magnitude), near-zero step ${formatStep(nearZeroStep)}.`
+      getExpr = `Quantize.DecodePower(${propName}, ${mx}, ${pw}, ${bits})`
+      setExpr = `Quantize.EncodePower(value, ${mx}, ${pw}, ${bits})`
+    } else {
+      continue
+    }
+
+    // Highest code the encoder can emit for this field. Both the linear quantizer (top code
+    // `2^bits - 1`) and the power quantizer (`(magnitude << 1) | sign` with an `bits-1`-bit
+    // magnitude, so top code `((2^(bits-1)-1) << 1) | 1 == 2^bits - 1`) share this bound.
+    const maxCode = 2 ** bits - 1
+
+    props.push({ propName, doc, getExpr, setExpr, step, maxCode })
+  }
+
+  if (props.length === 0) return null
+
+  const lines = []
+  lines.push(`public partial class ${msgProto.name}`)
+  lines.push('{')
+
+  // Decode on every get, encode on every set — no backing cache. The raw uint32 property is the
+  // single source of truth, so the float accessor can never disagree with the code on the wire
+  // (get-after-set returns the on-grid value a receiver decodes) and there is no stale-cache
+  // hazard when the raw field is mutated directly. Decode is a multiply-add; only power fields
+  // pay a MathF.Pow.
+  for (const { propName, doc, getExpr, setExpr, step } of props) {
+    lines.push(`${i}/// <summary>Coarsest quantization step of <see cref="${propName}Quantized"/>. Safe as an equality tolerance.</summary>`)
+    lines.push(`${i}public const float ${propName}QuantizedStep = ${formatFloat(step)};`)
+    lines.push(`${i}/// <summary>Float accessor for <see cref="${propName}"/>. ${doc}</summary>`)
+    lines.push(`${i}public float ${propName}Quantized`)
+    lines.push(`${i}{`)
+    lines.push(`${i}${i}get => ${getExpr};`)
+    lines.push(`${i}${i}set => ${propName} = ${setExpr};`)
+    lines.push(`${i}}`)
+    lines.push('')
+  }
+
+  lines.push(`${i}/// <summary>`)
+  lines.push(`${i}///     True when every quantized field holds a wire code within its declared bit width`)
+  lines.push(`${i}///     (<c>0 .. 2^bits-1</c>). The encoder never emits a code above this bound, so a larger`)
+  lines.push(`${i}///     value is a malformed/hostile message: decoding it would land far outside the field's`)
+  lines.push(`${i}///     <c>[min, max]</c> and, since the server relays raw codes verbatim, poison every observer.`)
+  lines.push(`${i}///     Reject before storing or relaying. Pure integer comparison — no decode.`)
+  lines.push(`${i}/// </summary>`)
+  lines.push(`${i}public bool AreQuantizedFieldsInRange() =>`)
+  props.forEach(({ propName, maxCode }, idx) => {
+    const prefix = idx === 0 ? '' : '&& '
+    const suffix = idx === props.length - 1 ? ';' : ''
+    lines.push(`${i}${i}${prefix}${propName} <= ${maxCode}u${suffix}`)
+  })
+
+  lines.push('}')
+  return lines
+}
+
+// ---------------------------------------------------------------------------
+// Per-file code generation (public entry point)
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a C# source file for a FileDescriptorProto, or null if the file
+ * contains no quantized uint32 fields.
+ * @returns {{name: string, content: string} | null}
+ */
+function generateCsharp(fileProto) {
+  const namespace = packageToNamespace(fileProto.package)
+
+  const protoFile = fileProto.name.split('/').pop()
+  const stem = snakeToPascal(protoFile.replace('.proto', ''))
+  const outName = `${stem}.Bitwise.cs`
+
+  const header = [
+    '// <auto-generated>',
+    '//   Generated by protoc-gen-bitwise. DO NOT EDIT.',
+    `//   Source: ${fileProto.name}`,
+    '// </auto-generated>',
+    '',
+    'using Decentraland.Networking.Bitwise;',
+    '',
+    `namespace ${namespace}`,
+    '{',
+  ]
+  const footer = ['', `} // namespace ${namespace}`]
+
+  const body = []
+  for (const msg of fileProto.messageType) {
+    const msgLines = generateMessage(msg)
+    if (msgLines === null) continue
+    // Indent each line by 4 spaces (inside the namespace block).
+    for (const line of msgLines) {
+      body.push(line ? '    ' + line : '')
+    }
+    body.push('')
+  }
+
+  if (body.length === 0) return null
+
+  const content = header.concat(body, footer).join('\n') + '\n'
+  return { name: outName, content }
+}
+
+module.exports = { generateCsharp }

package/protoc-gen-bitwise/options.js

@@ -0,0 +1,139 @@
+'use strict'
+
+/**
+ * Parser for the custom bitwise field options defined in options.proto.
+ *
+ * The descriptor decoder hands us the raw serialized FieldOptions bytes (it
+ * declares `options` as opaque bytes). We walk those bytes looking for the
+ * custom extension field numbers — protobuf preserves unknown/unregistered
+ * extension bytes, so they are always present even though no runtime here knows
+ * the extension schema. This mirrors the original options_pb2.py.
+ *
+ * Wire format: tag = (field_number << 3) | wire_type
+ *   wire_type 0 = varint, 1 = 64-bit, 2 = length-delimited, 5 = 32-bit
+ */
+
+const { readVarint, skipField } = require('./wire')
+
+// Extension field numbers as defined in options.proto.
+const QUANTIZED_FIELD_NUMBER = 50001
+const BIT_PACKED_FIELD_NUMBER = 50002
+const QUANTIZED_POWER_FIELD_NUMBER = 50003
+
+/** Parse a serialized QuantizedFloatOptions message: { min, max, bits }. */
+function parseQuantized(data) {
+  const opts = { min: 0.0, max: 0.0, bits: 0 }
+  let pos = 0
+  while (pos < data.length) {
+    let tag
+    ;[tag, pos] = readVarint(data, pos)
+    const fieldNum = tag >>> 3
+    const wireType = tag & 0x7
+    if (fieldNum === 1 && wireType === 5) {
+      // min (float)
+      opts.min = data.readFloatLE(pos)
+      pos += 4
+    } else if (fieldNum === 2 && wireType === 5) {
+      // max (float)
+      opts.max = data.readFloatLE(pos)
+      pos += 4
+    } else if (fieldNum === 3 && wireType === 0) {
+      // bits (uint32)
+      ;[opts.bits, pos] = readVarint(data, pos)
+    } else {
+      pos = skipField(data, pos, wireType)
+    }
+  }
+  return opts
+}
+
+/** Parse a serialized QuantizedPowerFloatOptions message: { max, pow, bits }. */
+function parseQuantizedPower(data) {
+  const opts = { max: 0.0, pow: 0.0, bits: 0 }
+  let pos = 0
+  while (pos < data.length) {
+    let tag
+    ;[tag, pos] = readVarint(data, pos)
+    const fieldNum = tag >>> 3
+    const wireType = tag & 0x7
+    if (fieldNum === 1 && wireType === 5) {
+      // max (float)
+      opts.max = data.readFloatLE(pos)
+      pos += 4
+    } else if (fieldNum === 2 && wireType === 5) {
+      // pow (float)
+      opts.pow = data.readFloatLE(pos)
+      pos += 4
+    } else if (fieldNum === 3 && wireType === 0) {
+      // bits (uint32)
+      ;[opts.bits, pos] = readVarint(data, pos)
+    } else {
+      pos = skipField(data, pos, wireType)
+    }
+  }
+  return opts
+}
+
+/** Parse a serialized BitPackedOptions message: { bits }. */
+function parseBitPacked(data) {
+  const opts = { bits: 0 }
+  let pos = 0
+  while (pos < data.length) {
+    let tag
+    ;[tag, pos] = readVarint(data, pos)
+    const fieldNum = tag >>> 3
+    const wireType = tag & 0x7
+    if (fieldNum === 1 && wireType === 0) {
+      // bits (uint32)
+      ;[opts.bits, pos] = readVarint(data, pos)
+    } else {
+      pos = skipField(data, pos, wireType)
+    }
+  }
+  return opts
+}
+
+/**
+ * Extract custom bitwise options from raw FieldOptions bytes.
+ *
+ * @param {Buffer|null} optionsRaw serialized FieldOptions, or null when unset.
+ * @returns {{quantized: object|null, bitPacked: object|null, quantizedPower: object|null}}
+ */
+function getFieldOptions(optionsRaw) {
+  if (!optionsRaw || optionsRaw.length === 0) {
+    return { quantized: null, bitPacked: null, quantizedPower: null }
+  }
+
+  let quantized = null
+  let bitPacked = null
+  let quantizedPower = null
+  let pos = 0
+
+  while (pos < optionsRaw.length) {
+    let tag
+    ;[tag, pos] = readVarint(optionsRaw, pos)
+    const fieldNum = tag >>> 3
+    const wireType = tag & 0x7
+
+    if (wireType === 2) {
+      let len
+      ;[len, pos] = readVarint(optionsRaw, pos)
+      const valueBytes = optionsRaw.subarray(pos, pos + len)
+      pos += len
+      if (fieldNum === QUANTIZED_FIELD_NUMBER) {
+        quantized = parseQuantized(valueBytes)
+      } else if (fieldNum === BIT_PACKED_FIELD_NUMBER) {
+        bitPacked = parseBitPacked(valueBytes)
+      } else if (fieldNum === QUANTIZED_POWER_FIELD_NUMBER) {
+        quantizedPower = parseQuantizedPower(valueBytes)
+      }
+      // else: unknown length-delimited field — already consumed.
+    } else {
+      pos = skipField(optionsRaw, pos, wireType)
+    }
+  }
+
+  return { quantized, bitPacked, quantizedPower }
+}
+
+module.exports = { getFieldOptions }

package/protoc-gen-bitwise/plugin.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+'use strict'
+
+/**
+ * protoc-gen-bitwise — protoc plugin that generates C# bitwise serialization code.
+ *
+ * Protocol:
+ *   1. protoc writes a serialised CodeGeneratorRequest to this process's stdin.
+ *   2. This plugin reads it, generates C# partial classes with float accessor
+ *      properties for every message that carries [(quantized)] field annotations.
+ *   3. A serialised CodeGeneratorResponse is written to stdout.
+ *
+ * Implemented in plain Node with a self-contained protobuf wire codec (see
+ * wire.js) so it runs with only `node` on PATH — no npm install required, even
+ * when invoked directly from a sibling checkout.
+ *
+ * Usage (from project root):
+ *   protoc \
+ *     --proto_path=proto \
+ *     --bitwise_out=generated/ \
+ *     --plugin=protoc-gen-bitwise=protoc-gen-bitwise/plugin.js \
+ *     proto/my_messages.proto
+ *
+ * On Windows, protoc needs an executable wrapper, e.g. a .cmd that runs:
+ *   node "<path>\protoc-gen-bitwise\plugin.js" %*
+ */
+
+const { decodeRequest, encodeResponse } = require('./wire')
+const { generateCsharp } = require('./generator_csharp')
+
+// CodeGeneratorResponse.Feature.FEATURE_PROTO3_OPTIONAL — advertised so protoc
+// does not reject the plugin when the schema uses proto3 `optional` fields.
+const FEATURE_PROTO3_OPTIONAL = 1
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    const chunks = []
+    process.stdin.on('data', (chunk) => chunks.push(chunk))
+    process.stdin.on('end', () => resolve(Buffer.concat(chunks)))
+    process.stdin.on('error', reject)
+  })
+}
+
+async function main() {
+  const requestBytes = await readStdin()
+  const request = decodeRequest(requestBytes)
+
+  // Lookup map for all file descriptors (parity with the Python plugin).
+  const fileByName = new Map()
+  for (const file of request.protoFile) fileByName.set(file.name, file)
+
+  const files = []
+  let error = null
+
+  for (const fileName of request.fileToGenerate) {
+    // Skip the options definition file itself — it has no messages to generate.
+    if (fileName === 'decentraland/common/options.proto') continue
+
+    const fileProto = fileByName.get(fileName)
+    if (!fileProto) continue
+
+    try {
+      const generated = generateCsharp(fileProto)
+      if (generated) files.push(generated)
+    } catch (exc) {
+      error = `protoc-gen-bitwise: error processing ${fileName}: ${exc && exc.message ? exc.message : exc}`
+    }
+  }
+
+  const response = encodeResponse({
+    error,
+    supportedFeatures: FEATURE_PROTO3_OPTIONAL,
+    files,
+  })
+
+  // Let the write flush before the process exits (do not call process.exit()).
+  process.stdout.write(response)
+}
+
+main().catch((exc) => {
+  const response = encodeResponse({
+    error: `protoc-gen-bitwise: ${exc && exc.stack ? exc.stack : exc}`,
+    supportedFeatures: FEATURE_PROTO3_OPTIONAL,
+    files: [],
+  })
+  process.stdout.write(response)
+})

package/protoc-gen-bitwise/runtime/cs/Quantize.cs

@@ -0,0 +1,70 @@
+// Decentraland.Networking.Bitwise — Quantize
+// Copy this file into your project alongside generated *.Bitwise.cs files.
+// ReSharper disable once RedundantUsingDirective
+
+using System;
+
+namespace Decentraland.Networking.Bitwise
+    // ReSharper disable once ArrangeNamespaceBody
+{
+    /// <summary>
+    ///     Static helpers for quantizing float values to/from unsigned integers.
+    ///     Intended for use with protobuf uint32 fields: the integer is transmitted
+    ///     as a protobuf varint, while the float accessor lives in a generated partial class.
+    /// </summary>
+    public static class Quantize
+    {
+        /// <summary>
+        ///     Encodes <paramref name="value" /> to a quantized <see cref="uint" />.
+        ///     Values outside [<paramref name="min" />, <paramref name="max" />] are clamped.
+        /// </summary>
+        public static uint Encode(float value, float min, float max, int bits)
+        {
+            var steps = (1u << bits) - 1;
+            var t = Math.Clamp((value - min) / (max - min), 0f, 1f);
+            return (uint)MathF.Round(t * steps);
+        }
+
+        /// <summary>Decodes a quantized <see cref="uint" /> back to a float.</summary>
+        public static float Decode(uint encoded, float min, float max, int bits)
+        {
+            var steps = (1u << bits) - 1;
+            return (float)encoded / steps * (max - min) + min;
+        }
+
+        /// <summary>
+        ///     Encodes <paramref name="value" /> with a power-law curve into an
+        ///     (<paramref name="bits" /> - 1)-bit linear unorm magnitude plus a sign bit. The magnitude is
+        ///     <c>(|value| / max)^(1/pow)</c>, so the inverse <see cref="DecodePower" /> reconstructs
+        ///     <c>sign * max * u^pow</c>. Zero is representable exactly; <paramref name="pow" /> &gt; 1
+        ///     concentrates resolution near zero. Magnitudes outside [0, <paramref name="max" />] are
+        ///     clamped.
+        ///     <para>
+        ///     The encoded layout puts the magnitude in the high bits and the sign in the LSB
+        ///     (<c>(magnitude &lt;&lt; 1) | sign</c>). This keeps the varint cost a function of
+        ///     magnitude rather than direction — a small <c>|value|</c> of either sign stays in a
+        ///     single varint byte. Zero canonicalizes to <c>0</c> (a zero magnitude never sets the
+        ///     sign bit), so proto3 still omits a stopped field entirely.
+        ///     </para>
+        /// </summary>
+        public static uint EncodePower(float value, float max, float pow, int bits)
+        {
+            var magnitudeSteps = (1u << (bits - 1)) - 1;
+            var t = Math.Clamp(MathF.Abs(value) / max, 0f, 1f);
+            var u = MathF.Pow(t, 1f / pow);
+            var magnitude = (uint)MathF.Round(u * magnitudeSteps);
+            var sign = value < 0f && magnitude != 0u ? 1u : 0u;
+            return (magnitude << 1) | sign;
+        }
+
+        /// <summary>Decodes a power-law quantized <see cref="uint" /> back to a float (inverse of
+        /// <see cref="EncodePower" />).</summary>
+        public static float DecodePower(uint encoded, float max, float pow, int bits)
+        {
+            var magnitudeSteps = (1u << (bits - 1)) - 1;
+            var u = (float)(encoded >> 1) / magnitudeSteps;
+            var magnitude = max * MathF.Pow(u, pow);
+            return (encoded & 1u) != 0 ? -magnitude : magnitude;
+        }
+    }
+}