Norito

Norito ہے Iroha کی canonical serialization پرت. یہ بائٹ فارمیٹ جب ہم مرتبہ استعمال کیا جاتا ہے، SDKs, CLI اوزار، Torii, Kura, اور پیدا شدہ آثار قدیمہ کو بالکل ایک ہی مفید بوجھ پر اتفاق کرنا ہوگا.

Norito کا استعمال کریں جب ڈیٹا اتفاق رائے ، دستخط ، ہیشنگ ، مستقل مزاجی ، یا کراس-SDK انٹرپرابلٹی کا حصہ ہو۔ JSON کا استعمال کریں اگر ایک اینڈ پوائنٹ واضح طور پر آپریٹرز ، ڈیش بورڈز ، یا فوری ڈیبگنگ کے لئے انسانی پڑھنے کے قابل پروجیکشن پیش کرتا ہے۔

جہاں Norito ظاہر ہوتا ہے

سطح	Norito کا استعمال کیسے کیا جاتا ہے
ٹرانزیکشنز اور سوالات	Torii کے ذریعے جمع کردہ دستخط شدہ لین دین اور استفسار کے مفید بوجھ کو Norito کے طور پر کوڈ کیا جاتا ہے۔
پیدائش	kagami genesis sign ایک دستخط شدہ .nrt بلاک پیدا کرتا ہے جو اسٹارٹ اپ پر بوجھ کے برابر ہوتا ہے۔
Torii ٹائپ کردہ جوابات	اختتامی پوائنٹس جو ٹائپ بائنری ردعمل کی حمایت کرتے ہیں Accept: application/x-norito کا استعمال کرتے ہیں۔
SDKs	Rust, Python, JavaScript, Kotlin/جاوا، Swift, اور Android گاہکوں کا استعمال Norito دستی طور پر جمع کردہ بائٹس کی بجائے بلڈرز یا پابندیاں۔
Kura اسٹوریج	بلاک مفید بوجھ، بازیابی سائیڈ کارز، فہرستیں اور کمیٹ مارکرز Norito فریم کردہ اعداد و شمار کے طور پر محفوظ کیے جاتے ہیں.
مظاہرہ	Nexus ، ڈیٹا کی دستیابی، SoraFS، سٹریمنگ، اور ایپ سے متعلق دستاویزات کا استعمال کرتے ہوئے جب دستاویز پر دستخط یا ہیش کرنا ضروری ہے تو Norito۔
سٹریمنگ	Norito سٹریمنگ میں Norito مانیٹس، سیگمنٹ ہیڈرز، کنٹرول فریم اور کنفارمیشن فکسچر استعمال ہوتے ہیں۔

Norito ایک ذہین معاہدے کی زبان نہیں ہے۔ یہ تعیناتی لفافہ اور کوڈیک ہے جو لین دین ، معاہدہ کالز ، مظاہرے ، اور ٹائپ کردہ API مفید بوجھ لے جاتا ہے۔

استعمال شدہ بوجھ کا ماڈل

ہر وائرڈ یا ڈسک پر پے لوڈ Norito کو ایک ہیڈر کے ذریعہ فریم کیا جاتا ہے جس کے بعد انکوڈ شدہ پےلوڈ بائٹس ہوتے ہیں۔ ہیڈرلیس ، یا ننگا ، پے لوڈز داخلی ہیشنگ ، بینچ مارکس اور اسسٹنٹ APIs کے لئے محفوظ ہیں جو نقل و حمل سے پہلے فوری طور پر نتیجہ کو ہیڈر میں لفافہ دیتے ہیں۔

ہیڈر فیلڈ	سائز	مقصد
جادو	4 بائٹ	ASCII NRT0, غیر Norito ڈیٹا کو ابتدائی طور پر مسترد کرنے کے لئے استعمال کیا جاتا ہے.
میجر	1 بائٹ	بڑے ورژن کو فارمیٹ کریں. موجودہ مفید بوجھ 0 کا استعمال کرتے ہیں۔
کم عمر	1 بائٹ	V1 کے لئے ڈکوڈ اشارہ. موجودہ قدر 0x00 ہے. پرچم ترتیب کی وضاحت کرتے ہیں.
اسکیم ہاش	16 بائٹ	غیر متوقع مفید بوجھوں کو مسترد کرنے کے لئے ٹائپ شدہ ڈیکوڈر کی طرف سے استعمال کردہ قسم کی شناخت۔
کمپریشن	1 بائٹ	0 = None، 1 = Zstd. نامعلوم اقدار مسترد کردیئے گئے ہیں.
استعمال شدہ بوجھ کی لمبائی	8 بائٹ	غیر کمپریسڈ مفید بوجھ کی لمبائی چھوٹی اینڈیئن u64 کے طور پر۔
CRC64	8 بائٹ	CRC64-XZ غیر کمپریسڈ مفید بوجھ کی جانچ پڑتال کی رقم۔
پرچم	1 بائٹ	کمپیکٹ لمبائیوں کے لئے ترتیب پرچم، پیک شدہ تسلسل، اور پیکڈ اسٹرکٹس.

ہیڈر 40 بائٹس ہے۔ ڈکوڈرز ٹائپ کردہ قدر کی تعمیر نو سے پہلے جادو ، ورژن ، سپورٹ شدہ پرچم ماسک ، پے لوڈ لمبائی ، چیک سوم اور اسکیما ہاش کو درست کرتے ہیں۔

ترتیب کے پرچم

Norito حتمی ہیڈر بائٹ میں ترتیب کے انتخاب کو ذخیرہ کرتا ہے۔ ڈیفالٹ v1 مددگاروں نے کمپیکٹ فی ویلیو لمبائی پریفیکسز کے لئے COMPACT_LEN (0x02) جاری کیا ہے۔ جب کال کرنے والے flags = 0x00 کے ساتھ انکوڈ کرتے ہیں تو واضح فکسڈ چوڑائی لمبائی کے پریفیکس پڑھنے کے قابل رہتے ہیں۔

پرچم	ہیکس	حالت	اثر
PACKED_SEQ	0x01	معاونت	متغیر سائز کے مجموعوں کو ایک آفسیٹ ٹیبل اور contiguous ڈیٹا بلاک کے ساتھ encodes.
COMPACT_LEN	0x02	ڈیفالٹ	ہر قدر کی لمبائی کے لئے کینونیکل غیر دستخط شدہ وارینٹس کا استعمال کرتا ہے۔
PACKED_STRUCT	0x04	معاونت	ان کوڈ حاصل پیدا structs کے طور پر پیک میدان مفید بوجھ کے طور پر
VARINT_OFFSETS	0x08	محفوظ شدہ	v1 میں مسترد کیا گیا؛ پیکڈ سیکوئنس آفسیٹس فکسڈ چوڑائی u64 ہیں.
COMPACT_SEQ_LEN	0x10	محفوظ شدہ	v1 میں مسترد؛ سب سے اوپر سطح کے تسلسل کی لمبائی ہیڈر فکسڈ چوڑائی u64 ہیں.
FIELD_BITSET	0x20	ضروریات سے معاونت	پیکڈ اسٹرکٹس کے لئے ایک بٹسٹ شامل کرتا ہے تاکہ صریح سائز کی ضرورت والے فیلڈز میں صرف سائز کا تعارف ہوتا ہے۔ PACKED_STRUCT اور COMPACT_LEN کی ضرورت ہوتی ہے۔

پرچم واضح ہیں۔ ڈیکوڈر پے لوڈ کی شکل ، چھوٹی ورژن ، یا ہیورسٹکس سے ترتیب کا نتیجہ نہیں نکالتے ہیں۔ نامعلوم یا غلط مجموعوں کو مسترد کیا جاتا ہے تاکہ تمام ہم مرتبہ ایک ہی طرح سے پےلوڈ کی ترجمانی کریں۔

کوڈنگ کے قواعد

Norito Iroha ڈیٹا ماڈل میں ظاہر ہونے والے عام اعداد و شمار کی شکلوں کے لئے تعیناتی ترتیب کا استعمال کرتا ہے:

• تاریں [len][utf8-bytes] ہیں؛ جب فعال ہو تو len COMPACT_LEN کے بعد آتا ہے۔
• جب COMPACT_LEN مقرر کیا جائے تو، ہر قدر کی لمبائی کو کمپیکٹ وارینٹ کا استعمال کیا جاتا ہے.
• جب COMPACT_LEN غائب ہے تو، ہر قدر کی لمبائی ایک 8 بائٹ چھوٹی اینڈین u64 ہے.
• تسلسل کی لمبائی کے ہیڈرز v1 میں 8 بائٹ چھوٹے اینڈین u64 فکسڈ ہیں.
• Vec<u8> فی بائٹ کی ایک لمبائی کے بجائے [len_u64][raw-bytes] کوڈ کیا جاتا ہے.
• پیک شدہ ترتیب (len + 1) monotonic u64 آفسیٹس کا استعمال کرتے ہیں جس کے بعد ایک ساتھ منسلک عنصر کے مفید بوجھ.
• نقشے فکسڈ u64 کے ساتھ اندراج کی گنتی کو انکوڈ کرتے ہیں اور تعیناتی کلیدی ترتیب کا استعمال کرتے ہیں۔ HashMap اندراجات کو انکوڈنگ سے پہلے کلید کے مطابق مرتب کیا جاتا ہے۔ BTreeMap اس کے قدرتی ترتیب کا استعمال کرتا ہے۔
• BigInt ایک u32 بائٹ لمبائی اور 512 بٹ کی ٹاپ کے ساتھ چھوٹی انڈین دو کی تکمیل بائٹس کا استعمال کرتا ہے.
• Numeric کو (mantissa, scale) کے طور پر کوڈ کیا جاتا ہے، جہاں mantissa انٹیجر ویلیو اسٹوریج کرتا ہے اور پیمانے کٹوتی ہندسوں کی تعداد کو ذخیرہ کرتا ہے۔

یہ قواعد دستخطوں اور ہیشز کے لئے اہم ہیں۔ دو SDKs جو ایک ہی منطقی لین دین کی تعمیر کرتے ہیں انہیں ایک ہی کینونیکل بائٹس پیدا کرنا ضروری ہے۔

اسکیم ہاشس

ٹائپ کردہ Norito پےلوڈ ہیڈر میں 16 بائٹ کے اسکیما ہیش لے جاتے ہیں۔ ڈیفالٹ ہیش مکمل طور پر اہل قسم کے نام سے اخذ کیا جاتا ہے۔ بلڈز جو ڈھانچے کے شیما ہیشنگ کو قابل بناتے ہیں وہ اس کی بجائے کینونیکل شیما سے ہیش نکالتے ہیں۔

ٹائپڈ ڈیکوڈر اسکیما عدم مطابقت کو مسترد کرتے ہیں۔ یہ کلائنٹس کو غلط قسم کے طور پر درست Norito فریم کی غلطی سے بچاتا ہے اور جب ایک SDK فکسچر بنڈل نوڈ ڈیٹا ماڈل سے انحراف کرتا ہے تو عام خرابی کا موڈ ہوتا ہے۔

کمپریشن اور رفتار

Norito منطقی مفید بوجھ کو تبدیل کیے بغیر صریح اور موافقت پذیر کمپریشن کی حمایت کرتا ہے:

خصوصیت	مقصد
to_bytes	ایک ہیڈر کو انکوڈ کریں اور اس کے بعد غیر کمپریسڈ پلے لوڈ کریں۔
to_compressed_bytes	Zstd کے ساتھ انکوڈ اور ہیڈر میں کمپریشن ٹیگ ریکارڈ.
to_bytes_auto	یہ فیصلہ کرنے کے لئے تعیناتی ہیورسٹکس کا استعمال کریں کہ آیا کمپریشن قابل قدر ہے۔
CRC64 رفتار	ہر جگہ پورٹیبل CRC64-XZ استعمال کرتا ہے، جب دستیاب ہو تو x86_64 پر CLMUL یا aarch64 پر PMULL کے ساتھ۔
GPU CRC64 اور کمپریشن	اختیاری دھات یا CUDA مددگار بڑے مفید بوجھ کو تیز کر سکتے ہیں، پھر CPU راستوں پر واپس گر سکتے ہیں.

ہارڈ ویئر کی رفتار کبھی بھی ڈکوڈ کردہ مواد کو تبدیل نہیں کرتی ہے۔ CRC اور JSON تیز کرنے والوں کو پورٹ ایبل آؤٹ پٹ بِٹ-بِٹ سے ملنا چاہئے۔ Zstd فریم بائٹس CPU اور GPU کوڈر کے مابین مختلف ہوسکتے ہیں ، لیکن ڈیکوڈ شدہ مفید بوجھ اور Norito ہیڈر میٹا ڈیٹا توثیق کے ل deterministic مستقل رہ جاتے ہیں۔

JSON امداد

Norito میں اختتامی پوائنٹس اور ٹولنگ کے لئے ایک مقامی JSON اسٹیک شامل ہے جو JSON کی ضرورت ہوتی ہے بغیر Norito قسم کے نظام کو چھوڑنے کے بغیر۔

JSON خصوصیت	استعمال کی صورت
norito::json::{to_json, from_json}	Deterministic typed JSON کوڈ/decode۔
خوبصورت اور مصنفین کے مددگار	CLI آؤٹ پٹ، فکسچر اور سٹریمنگ std::io انضمام۔
DOM اقدار	Norito کے JSON ویلیو ماڈل کی طرف سے پروگراماتی ہینڈلنگ۔
تیز رفتار ٹائپ JSON	ہاٹ DTO راستوں کے لئے ڈھانچے کی ٹیپ پر مبنی ڈیکوڈ / کوڈ.
صفر کاپی ریڈر	ٹوکن سکیننگ جو ممکنہ طور پر ان پٹ سے تاروں کو قرض لیتا ہے۔
مرحلے 1 تیز کرنے والے	اختیاری AVX2 ، NEON، دھات، یا CUDA ساختہ انڈیکسنگ سکالر فال بیک کے ساتھ۔

Iroha کوڈ ترجیح دینا چاہئے norito::json ٹائپنگ کے لئے مددگار API مفید بوجھ۔ سادہ شامل کرنا serde_json پیداواری راستوں کے لئے اسکیما اور فیلڈ ہینڈلنگ رویے سے متوقع انحراف کا خطرہ SDKs اور Torii نکالنے والے۔

مشتق امداد

Rust ڈیٹا کی اقسام عام طور پر دستی کوڈک کوڈ کے بجائے مشتق میکرو کا استعمال کرتی ہیں۔ مشتق پرت Norito بائنری کوڈکس ، اسکیمز اور JSON مددگار پیدا کرسکتی ہے.

عام فیلڈ صفات یہ ہیں:

وصف	اثر
#[norito(rename = "other")]	schema اور JSON مطابقت کے لئے ایک مستحکم serialized نام کا استعمال کرتا ہے.
#[norito(skip)]	کوڈر فیلڈ کو چھوڑ دیتا ہے۔ ڈیکوڈر اس کی Default قدر فراہم کرتا ہے۔
#[norito(default)]	Default کا استعمال کرتا ہے جب کسی ڈیکوڈ شدہ مفید بوجھ میں فیلڈ نہیں ہوتا ہے۔
#[norito(skip_serializing_if = "...")]	JSON سے کھیتوں کو خارج کر دیتا ہے جب پیش گوئی مطابقت رکھتا ہے، جبکہ ڈیٹرمینسٹک ڈیکوڈنگ کی ڈیفالٹس کو برقرار رکھنے کے ساتھ.

مشتق بھی جہاں ممکن ہو کوڈ کی لمبائی کے اشارے اور عین مطابق لمبائی کا حساب لگاتے ہیں۔ کوڈر ان اشاروں کا استعمال بفرز ذخیرہ کرنے اور اضافی کاپیاں سے بچنے کے لئے کرتے ہیں۔

خانہ خصوصیت خاندان

جب Iroha یا SDK منسلکات کو ماخذ سے بناتے ہیں تو ، Norito خصوصیات منتخب کریں کہ کون سے ہیلپرز اور تیز کرنے والے دستیاب ہیں:

خصوصیت خاندان	یہ کیا کام کرتا ہے؟
derive	بائنری، شیما، اور JSON مشتقوں کے لئے دوبارہ برآمد شدہ طریقہ کار میکرو۔
compression	ہیڈر فریم والے مفید بوجھوں کے لیے Zstd سپورٹ۔
packed-seq	آفسیٹ ٹیبلز کا استعمال کرتے ہوئے پیک کردہ مجموعہ ترتیب.
packed-struct	پیک شدہ مشتق پیدا کردہ ڈھانچے کی ترتیب.
compact-len	Varint ہر قدر کی لمبائی کے لئے prefixes.
columnar	Norito کالم بلاکس، موافقت پذیر AoS/NCB سطر کوڈیک، اور سکین بھاری راستے کے لئے قرضے شدہ نظارے؛ ڈیفالٹ node-codec خصوصیت سیٹ میں شامل.
strict-safe	غلط راستے میں گھبراہٹ کو منظم غلطیوں میں تبدیل کرتا ہے.
simd-accel	CPU رفتار، جہاں دستیاب ہے، کے ساتھ deterministic fallback.
json	مقامی JSON تجزیہ کار، لکھنے والا، DOM، ٹائپ شدہ مشتق اور تیز راستوں.
json-std-io	JSON اسٹیک پر پرتوں والے قارئین اور لکھنے والوں کی مدد کریں.
metal-stage1، cuda-stage1	اختیاری GPU JSON ساختی انڈیکس بیکڈ۔
metal-stage2	JSON ساختی ٹیپ کے لئے اختیاری دھات میٹا ڈیٹا درجہ بندی۔
metal-crc64، cuda-crc64	بڑے مفید بوجھ کے لئے اختیاری GPU CRC64 اسسٹنٹ۔
gpu-compression	بڑی مفید بوجھ کے لئے اختیاری دھات یا CUDA Zstd رفتار.
stage1-validate	ڈیبگ کی توثیق جو تیز رفتار JSON ساختی انڈیکس کو سکالر آؤٹ پٹ کے مقابلے میں موازنہ کرتی ہے۔

خصوصیت کی دستیابی SDKs اور ریلیز پروفائلز کے درمیان مختلف ہوسکتی ہے۔ وائر فارمیٹ مقامی بلڈ پرچموں کے بجائے ہیڈر اور شیما سے چلتا رہتا ہے۔

Torii اور Norito RPC

Torii بہت سے آپریٹر راستوں کے لئے JSON کو بے نقاب کرتا ہے، لیکن ٹائپ شدہ بائنری راستوں کا استعمال کرتے ہیں Norito. موجودہ ٹائپ کردہ Norito HTTP جسموں کے لئے میڈیا کی قسم application/x-norito ہے.

Norito ٹائپ کردہ اختتامی نقطہ قبول کرنے یا واپس آنے پر ان ہیڈر کا استعمال کریں:

Content-Type: application/x-norito
Accept: application/x-norito

جب ایک اختتامی نقطہ دونوں نمائندگیوں کی حمایت کرتا ہے تو، گاہکوں کو واضح ترجیحات کی فہرست بھیج سکتے ہیں:

Accept: application/x-norito, application/json

ڈیکوڈ کی ناکامیاں Torii ٹائپ کردہ غلطیوں کے طور پر ظاہر ہوتی ہیں اور ٹیلی میٹری کے ذریعہ گنتی کی جاتی ہیں۔ عام وجوہات میں غلط جادو ، غیر تعاون یافتہ ورژن ، غیر معاون خصوصیت کا پرچم ، چیک سوم مماثلت ، غلط فارمیٹ شدہ UTF-8 ، غلط اینوم ٹیگ ، اور اسکیما مماثلت شامل ہیں۔

Norito RPC ٹرانسپورٹ کی ترتیب کے ذریعے منتخب کیا جاتا ہے۔ آپریٹر ڈیش بورڈز کو درخواستوں کی تاخیر ، ناکامیوں ، فعال کنکشنز ، ردعمل بائٹس اور torii_norito_decode_failures_total کو JSON ٹریفک سے علیحدہ طریقے سے ٹریک کرنا چاہئے۔

Norito سٹریمنگ

Norito سٹریمنگ میڈیا اور ریئل ٹائم ٹرانسپورٹ سطحوں پر ایک ہی تعیناتی نقطہ نظر کی توسیع کرتی ہے۔ اس کے اہم ٹکڑے یہ ہیں:

سٹریمنگ کی خصوصیت	مقصد
مظاہرہ	سیگمنٹ کے وعدوں، رازداری کے راستوں، صلاحیتوں، کوڈک پروفائلز، خفیہ کاری سوٹ اور مواد کی کلید میٹا ڈیٹا کا اعلان کریں۔
سیگمنٹ ہیڈر	بانڈ سیگمنٹ نمبر، مدت، ٹکڑے شمار، ٹائمنگ، انٹروپی موڈ، آڈیو خلاصہ، اور مرکل جڑوں.
ٹکڑے ٹکڑے وعدے	ناظرین اور ریلے کو خدمت یا ڈیکوڈنگ سے پہلے دستی کے ساتھ مفید بوجھ ٹکڑے کی تصدیق کرنے دیں.
کنٹرول فریم	واضح اعلانات، رائے، اہم اپ ڈیٹس اور صلاحیتوں کی بات چیت کو لے کر جائیں۔
HPKE اہم اپ ڈیٹس	ٹرانسپورٹ کے رازوں کو متفقہ سویٹ کا استعمال کرتے ہوئے گھومیں اور تنہا بڑھتی ہوئی کاؤنٹرز.
صلاحیتوں کے بارے میں مذاکرات	خصوصیات کے بٹس، ڈیٹا گرام کی حدود، ریپڈ بیک کی ترتیب اور رازداری کی ضروریات کی حمایت کرتا ہے.
FEC اور رائے	نقصان ریئل ٹائم راستوں کے لئے Deterministic وصول کنندہ رپورٹس اور پارٹی فیصلے کا استعمال کرتا ہے.
مطابقت ویکٹر	کراس زبان فکسچر ثابت SDKs ایک ہی manifolds، segments، اور entropy بہاؤ کو ڈیکوڈ.

اسٹریمنگ مخصوص کوڈیکس اور انٹروپی پروفائلز بنیادی Norito ٹرانزیکشن / استفسار فارمیٹ سے الگ ہیں ، لیکن ان کے مانیٹس اور کنٹرول ڈیٹا اب بھی Norito کا استعمال کرتے ہیں لہذا روٹنگ ، بلنگ ، ری پلے ، اور آڈٹ ثبوت دوبارہ پیش کیا جا سکتا ہے.

آپریشنل رہنمائی

• SDK بلڈرز اور جنریٹڈ بائنڈنگز کو ہاتھ سے تیار کردہ Norito بائٹس کی بجائے ترجیح دیں۔
• اسکیما کی عدم مطابقت کو ورژن یا فکسچر کے مسئلے کے طور پر علاج کریں، transient network failure کے طور پر نہیں.
• آرکائیو .nrt ، .norito، اور ان کی پیداوار کرنے والے ریلیز یا حادثے کے بنڈل میں ظاہر شدہ آثار۔
• دستخط شدہ ، ہیشڈ یا برقرار رکھنے والے اعداد و شمار کے لئے Norito کو سچائی کا ذریعہ کے طور پر استعمال کریں۔ ڈیش بورڈز اور دستی معائنہ کے ل projections JSON پروجیکشن کا استعمال کریں۔
• کسی نئے Torii ٹائپ کردہ اختتامی نقطہ کو شامل کرتے وقت، اس بات کی دستاویز کریں کہ آیا یہ JSON، Norito، یا دونوں کو قبول کرتا ہے، اور /openapi میں معاون مواد کی اقسام کو ظاہر کرنا۔
• ایکسلریٹر کو چالو کرنے سے پہلے، سکالر آؤٹ پٹ کے خلاف پارٹی ٹیسٹ چلائیں. اگر ایکسیلیٹر ناکام ہوجاتا ہے تو، تعیناتی سکالر فال بیک کا استعمال کریں. فائدہ مند بوجھ کی semantics تبدیل نہیں کیا جانا چاہئے.

متعلقہ صفحات

• Torii اختتام پوائنٹس
• پیدائش کا حوالہ
• ڈیٹا ماڈل اسکیم
• JavaScript /TypeScript SDK
• Python SDK
• Swift اور آئی او ایس SDK

اپ اسٹریم ریفرنسز

• Norito فارمیٹ کی تفصیلات
• Norito خانہ README