Norito

Norito է Iroha Կանոնիկ շարականացման շերտ. Այն օգտագործվում է բայթ ձեւաչափը, երբ զուգընկերները, 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/Java, Swift, եւ Android հաճախորդների օգտագործումը Norito շինարարներ կամ կապեր ձեռքով հավաքված բայթների փոխարեն:
Kura պահեստավորում	Բլոկային օգտակար բեռնվածքները, վերականգնման կողմնակի մեքենաները, ցուցակները եւ պարտավորությունների նշանները պահվում են որպես Norito շրջանակված տվյալներ:
Մանիֆեսներ	Nexus, տվյալների մատչելիություն, SoraFS, հոսքային եւ հավելվածի դեմ ուղղված մանիֆեսները օգտագործվում են Norito, երբ մանիֆեսիոն պետք է ստորագրվի կամ վերանայվի:
Թողարկում	Norito Streaming- ը օգտագործում է Norito մանիֆեսներ, հատվածների գլխավորագրեր, վերահսկողության շրջանակներ եւ համապատասխանություն ունեցող սարքեր:

Norito ոչ թե խելացի պայմանագրի լեզու է, այլ դետերմինիստական փաթեթ եւ կոդեկ, որը բեռնում է գործարքներ, պայմանագրային զանգեր, մանիֆեսներ եւ տիպավորվում API օգտակար ծանրաբեռնվածքներ:

Օգտակար բեռի մոդել

Յուրաքանչյուր կլոր կամ սկավառակի վրա Norito օգտակար բեռնվածություն շրջանակվում է գլխավորությամբ, որին հաջորդում են կոդավորված օգտակար բեռների բայթները: Անհետաքրքիր կամ մերկ օգտակար բարձիկները հատկացվում են ներքին հաշինգի, benchmarks- ի եւ օգնական 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։

Պիտակ	Hex	Պաշտոն	Արդյունք
PACKED_SEQ	0x01	Աջակցություն	Կոդավորում է փոփոխական չափի հավաքածուներ օֆսետային աղյուսակով եւ հարակից տվյալների բլոկի հետ:
COMPACT_LEN	0x02	Նախադրյալ	Օգտագործում է քանոնիկ չստորագրված տերեւներ յուրաքանչյուր արժեքի երկարության նախանշանակների համար:
PACKED_STRUCT	0x04	Աջակցություն	Կոդավորում է ստացված structs որպես փաթեթավորված դաշտային payloads.
VARINT_OFFSETS	0x08	Պահանջված	Բացառված v1- ի մեջ, փաթեթավորված հաջորդականության փոխհատուցումներն են հաստատված լայնությամբ u64.
COMPACT_SEQ_LEN	0x10	Պահանջված	V1-ում մերժված. բարձր մակարդակի հաջորդականության երկարության գլխավորագրերը ֆիքսված լայնությամբ u64 են:
FIELD_BITSET	0x20	Պահանջներով աջակցված	ավելացնում է բիթսեթ փաթեթավորված structs այնպես որ միայն դաշտերը, որոնք պահանջում են բացասական չափերի կրկնել չափի նախադրյալներ. Requires PACKED_STRUCT եւ COMPACT_LEN.

Պիտակները բացասական են: Դեկոդիչները չեն ենթադրում դասակարգումը օգտակար բեռնվածքի ձեւից, փոքր տարբերակներից կամ հյուրիստիկայից: Անհայտ կամ անվավեր համադրությունները մերժվում են, որպեսզի բոլոր զուգընկերները մեկնաբանեն օգտակար բեռը նույն կերպ.

Կոդավորման կանոններ

Norito օգտագործում է Iroha տվյալների մոդելում հայտնված ընդհանուր տվյալների ձեւերի համար որոշմանական դասակարգումներ.

• Կապերը [len][utf8-bytes]; len-ը հաջորդում է COMPACT_LEN-ին, երբ բացված է:
• Երբ COMPACT_LEN սահմանվում է, յուրաքանչյուր արժեքի երկարությունը օգտագործվում է կոմպակտ varint:
• Երբ COMPACT_LEN բացակայում է, յուրաքանչյուր արժեքի երկարությունը 8-բայթանոց փոքր-մասավոր u64 է:
• Սեկվենցիայի երկարության գլուխները կոշտ են 8-բայտ փոքր-ինչ u64 v1- ում:
• 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 ամենուր, օգտագործելով CLMUL x86_64 կամ PMULL aarch64- ում, երբ հասանելի են:
GPU CRC64 եւ սեղմում	Ընտրական Մետաղի կամ CUDA օգնականները կարող են արագացնել մեծ օգտակար բեռնվածքները, ապա վերադառնալ CPU ուղին:

Հարդքորային արագացումը երբեք չի փոխում դեկոդավորված բովանդակությունը: CRC եւ JSON արագացուցիչները պետք է համապատասխանեն պորտալ արտադրանքի բիթ-բիտին: Zstd շրջանակի բայթները կարող են տարբերվել CPU եւ GPU կոդավորիչների միջեւ, բայց դեկոդացված օգնական բեռը եւ Norito գլխագրի մետատաղերը մնում են վավերացման համար որոշակի:

JSON Աջակցություն

Norito ներառում է վերջային կետերի եւ գործիքների համար տեղական JSON փաթեթ, որոնք անհրաժեշտ են JSON ՝ առանց դուրս գալու Norito տիպի համակարգից:

JSON հատկություն	Օգտագործման դեպք
norito::json::{to_json, from_json}	Դետերմինիստիկ տիպավորված JSON կոդ/կոդ:
Գեղեցիկ եւ գրող օգնականներ	CLI արտադրանքի, սարքերի եւ հոսանքի std::io ինտեգրման համար:
DOM արժեքներ	Ծրագրային մանիպուլյացիան Norito-ի JSON արժեքի մոդելով:
Արագ տիպված JSON	Կառուցվածքային ժապավենների վրա հիմնված տաք DTO ուղիների համար դեկոդ/կոդավորում:
Ցերո կոպիային ընթերցող	Ցուցանիշի սկանավորում, որը հնարավոր է ներմուծումից վարկեր է վերցնում:
1-րդ փուլի արագացուցիչներ	Ընտրական AVX2, NEON, Մետաղային կամ CUDA կառուցվածքային ինդեքսավորում՝ սկանալային անկման հետ:

Iroha կոդը պետք է նախընտրի norito::json օգնականները տիպավորված API օգտակար բեռների համար: Արտադրման ուղիների մեջ պարզ serde_json ավելացնելը կարող է տարբերվել SDKs եւ Torii արդյունահանողների կողմից ակնկալվող սխեմայից եւ դաշտային վարքագծի հետ:

Ծանոթացիկ աջակցություն

Rust տվյալների տեսակները սովորաբար օգտագործում են ծագումային մակրոներ, այլ ոչ թե ձեռնական կոդեկային կոդ: Ծագման շերտը կարող է արտադրել Norito բինար կոդեկներ, սխեմաներ եւ JSON օգնականներ:

Համատարած դաշտային հատկանիշները հետեւյալն են.

Attribute	Արդյունք
#[norito(rename = "other")]	Օգտագործում է կայուն սերիալացված անվանումը schema եւ JSON համատեղելիության համար.
#[norito(skip)]	Կոդավորիչը բաց է թողնում դաշտը: Դեկոդերը տրամադրում է իր Default արժեքը:
#[norito(default)]	Օգտագործում է Default այն դեպքում, երբ դեկոդավորված օգտակար բեռը չի կրում դաշտը:
#[norito(skip_serializing_if = "...")]	Բաց թողնում է JSON դաշտերը, երբ predicate համընկնում է, պահպանելով deterministic dekoding անսահմանափակ.

Դերիվները նաեւ բացահայտում են կոդավորված երկարության հուշեր եւ ճշգրիտ երկարության հաշվարկներ, երբ դա հնարավոր է: Կոդավորողները օգտագործում են այդ հուշերը պահեստային բուֆերների համար եւ խուսափում են լրացուցիչ պատճեններից:

Կապի առանձնահատկության ընտանիքներ

Երբ Iroha կամ SDK կապումները կառուցվում են աղբյուրից, Norito առանձնահատկությունները ընտրում են այն օգնականներն ու արագացուցիչները, որոնք մատչելի են.

Բնութաբանական ընտանիք	Ինչ է այն թույլ տալիս
derive	Բինարային, սխեմայի եւ JSON ծագումների համար վերարտահանված ընթացակարգային մակրոներ:
compression	Zstd աջակցություն գլխուղեղի շրջանակներով օգտակար բեռների համար:
packed-seq	Փաթեթավորված հավաքածու դասակարգումներ, օգտագործելով offset աղյուսակներ.
packed-struct	Փաթեթավորված ծագումներով ստեղծված կառուցվածքային դասակարգումներ:
compact-len	Varint- ի երկարության նախադրյալները ըստ արժեքի:
columnar	Norito Սյունակի բլոկներ, հարմարվողական AoS/NCB տողային կոդեկներ եւ վառված դիտումներ սկանավորման ծանր ուղիների համար. ներառված են նախանշյալ node-codec հատկանիշների հավաքածուում:
strict-safe	Դեկոդավորում է խախտելի ուղիների պանիկները կառուցված սխալների մեջ:
simd-accel	CPU արագացում, երբ հասանելի է, դետերմինիստիկ հետընթացով:
json	Native 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	Debug վավերացում, որը համեմատում է արագացված JSON կառուցվածքային ինդեքսները skalar արտադրանքի հետ:

Մատչերի հասանելիությունը կարող է տարբերվել SDKs եւ թողարկման պրոֆիլների միջեւ: Կապի ձեւաչափը շարունակում է կառավարվել գլխավորությամբ եւ սխեմանով, այլ ոչ թե տեղական կառուցվածքի դրոշներով:

Torii եւ Norito RPC

Torii exposes 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, անվավեր enum նշանը եւ սխեմայի անհամատեղելիությունը:

Norito RPC տրանսպորտը ընտրվում է տրանսպորտային կոնֆիգուրացիայի միջոցով: Օպերատորների դաշբੋਰਡները պետք է հետեւեն խնդրանքների ուշացման, ձախողումների, ակտիվ կապերի, արձագանքման բայտների եւ torii_norito_decode_failures_total երթեւեկության առանձին JSON:

Norito Հոսքային հաղորդում

Norito Streaming- ը ընդլայնում է նույն դետերմինիստական մոտեցումը լրատվամիջոցների եւ իրական ժամանակի տրանսպորտային մակերեւույթների վրա:

Streaming առանձնահատկությունը	Նպատակ
Մանիֆեսներ	Հայտարարել հատվածային պարտավորությունները, գաղտնիության ուղիները, հնարավորությունները, կոդեկի պրոֆիլը, ծածկագրման հավաքածուն եւ բովանդակության առանցքային մեթադատները:
Segment headers	Կապեք հատվածի համարը, տեւողությունը, մասերի քանակը, ժամանակավորությունը, էտրոպիական ռեժիմը, ձայնային ամփոփումը եւ Merkle արմատները:
Մասային պարտավորություններ	Թույլ տվեք դիտորդներին եւ ռեայերին ստուգել օգտակար բեռի հատվածները նախքան սպասարկումը կամ կոդավորմանը:
վերահսկողության շրջանակներ	Տեղեկատվություն, արձագանքներ, հիմնական թարմացումներ եւ հնարավորությունների բանակցություններ:
HPKE հիմնական թարմացումներ	Շրջեք տրանսպորտային գաղտնիքները' օգտագործելով բանակցությունների սվիտը եւ միանգամայն աճող հաշվիչները:
Հասունակության բանակցությունները	Intersects աջակցված առանձնահատկությունների բիթներ, datagram սահմանափակումները, հետադարձ կապի տեքստը եւ գաղտնիության պահանջները.
FEC եւ հետադարձ կապ	Օգտագործում է վճռական ստացողի հաշվետվություններ եւ զուգահեռ որոշումներ կորուստների իրական ժամանակով ուղիները.
Համապատասխանության վեկտորներ	Միջերկրյա լեզվական սարքերը ապացուցում են, որ SDKs կոդավորում է նույն մանիֆիսները, հատվածները եւ ինտրոպիական հոսքը:

Streaming-specific codecs եւ entropy profiles- ը առանձին են հիմնական Norito գործարքի / հարցման ձեւաչափից, բայց դրանց մանիֆեսներն ու վերահսկողության տվյալները դեռ օգտագործում են Norito, այնպես որ երթեւեկումը, բյուջենը, կրկնությունը եւ աուդիտի ապացույցները շարունակում են վերարտադրվել։

Օպերացիոն ուղեցույց

• Նախընտրում են SDK շինարարներ եւ ստեղծված կապեր ձեռքով պատրաստված Norito բայթների փոխարեն:
• Բարեւեք սխեմայի անհամապատասխանությունը որպես տարբերակի կամ սարքավորման խնդիր, այլ ոչ թե անցումային ցանցի ձախողման համար:
• Արխիվ .nrt, .norito, եւ հրատարակման կամ միջադեպի փաթեթում գտնվող երեւույթները, որոնք արտադրել են դրանք:
• Օգտագործեք Norito որպես ճշմարտության աղբյուր ստորագրված, хэշված կամ մշտական տվյալների համար: Օգտագործիր JSON նախագծերը վահանակային սեղանների եւ ձեռքով ստուգման համար:
• Torii նոր տիպված վերջային կետ ավելացնելիս փաստաթղթագրեք, թե արդյոք այն ընդունում է JSON, Norito կամ երկուսն էլ, եւ բացատրեք աջակցվող բովանդակության տեսակները /openapi մեջ:
• Նախքան արագացուցիչի ակտիվացումը, վարեք զուգահեռության փորձարկումներ skalar արտադրանքի դեմ: Եթե արագացնողը ձախողվում է, օգտագործեք deterministic scalar fallback- ը: Օգտակար բեռի սեմանտիկան պետք է մնա անփոխարինելի:

Կապակցված էջեր

• Torii վերջնական կետեր
• Ծննդոցային հղում
• Տվյալների մոդելային սխեմա
• JavaScript /TypeScript SDK
• Python SDK
• Swift եւ iOS SDK

Վերածննդային հղումներ

• Norito ձեւաչափի բնութագրեր
• Norito տուփը README