feat(idl-v2): intoduce IDL V2 (spec, ast, parser, gen) and Sails Header (spec, routing, code gen)

[vobradovich]

This PR introduces significant enhancements to the Sails framework with IDL v2, focusing on routing by header in programs, services, and generated clients. Here's a breakdown of the changes:

• Sails Message Header Implementation
• Interface ID System
• Enhanced Program and Service Routing
• IDL Meta Enhancements
• Client Generation Improvements
• Macro System Updates

This represents a major architectural shift in how Sails programs handle service routing, moving from a simple byte-route model to a more sophisticated header-based system with interface IDs for improved scalability and extensibility.

[gemini-code-assist]

Summary of Changes

Hello @vobradovich, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request overhauls the core interface definition and message handling mechanisms within the Sails framework. It introduces a robust IDL V2 for defining program and service structures and a new Sails Header for efficient, deterministic message routing. These foundational changes enhance the system's extensibility, developer experience, and compatibility with external tooling by providing clear, standardized protocols for interaction.

Highlights

• IDL V2 Introduction: Introduced a new version of the Interface Definition Language (IDL V2) along with its specification, Abstract Syntax Tree (AST), parser, and code generator. This new version provides enhanced capabilities and a more structured approach to defining interfaces.
• Sails Header for Message Routing: Implemented a standardized Sails Header (v1) for asynchronous messages. This header facilitates deterministic routing, improves off-chain decodability, and enables unique service fingerprinting without altering the underlying Gear message layout. Detailed specifications for the header, interface IDs, and ReflectHash are provided.
• Client Generation Logic Refinement: Updated the client generation process to align with IDL V2 and the new Sails Header. This includes changes to how service methods and events are identified and encoded/decoded, leveraging new ROUTE_ID and INTERFACE_ID constants for improved clarity and efficiency.
• Dependency Updates and Refactoring: Performed extensive dependency updates across Cargo.lock and Cargo.toml files, notably upgrading askama and related crates. Several internal crates like sails-idl-parser were replaced with sails-idl-parser-v2, and new crates like sails-reflect-hash were introduced to support the new IDL and header specifications.
• Comprehensive Documentation: Added new documentation files (IDL_V2_SPEC.md, INTERFACE_ID_SPEC.md, REFLECT_HASH_SPEC.md, SAILS_HEADER_V1_SPEC.md) to thoroughly explain the new specifications and their implications for developers.

Ignored Files

• Ignored by pattern: .github/workflows/** (1)
  • .github/workflows/rs-ci.yml

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request primarily focuses on updating the sails-rs framework to a new IDL v2 specification and integrating a new message header format. Key changes include upgrading askama and related dependencies, introducing sails-idl-parser-v2 and sails-reflect-hash crates, and updating Cargo.toml files accordingly. The README.md has been revised to reflect the new 'Sails Header v1' payload encoding, which uses deterministic interface_id, entry_id, and route_idx for message routing. Benchmark IDL files and client generation logic have been refactored to align with the new IDL v2 format, including adding ReflectHash derives to various structs and enums for structural hashing. Several test files and examples have been updated to use the new message header for encoding/decoding and to correctly handle service routing via route_idx and interface_id instead of string-based routes. Documentation for IDL V2, Interface ID, and ReflectHash specifications has been added. Review comments highlighted the need to correct an example sorting order in the Interface ID spec, ensure enum names are included in structural hashes to prevent collisions, fix an inconsistency in the Sails Header v1 example regarding header length, refactor duplicated client generation code into a helper function, and correct a typo in the IDL V2 spec.

[gemini-code-assist]

There are a couple of inconsistencies in this example:

• The hlen (header length) is shown as 0B (11 bytes), but the specification states the base header is 16 bytes. It should be 0x10.
• The comment Payload bytes follow immediately after byte offset 11 is also incorrect due to the header size. It should be offset 16.

The same issue is present in Example B.

[github-actions]

🔬 Benchmark Comparison

Benchmark	Current	Baseline	Change	Change %	Status
compute	465_522_069_624	465_485_012_100	+37_057_524	+0.01%	✅
alloc-0	596_676_950	561_979_259	+34_697_691	+6.17%	❌
alloc-12	600_247_037	565_520_788	+34_726_249	+6.14%	❌
alloc-143	760_060_748	725_298_850	+34_761_898	+4.79%	⚠️
alloc-986	863_052_442	828_290_220	+34_762_222	+4.20%	⚠️
alloc-10945	2_217_294_085	2_042_673_536	+174_620_549	+8.55%	❌
alloc-46367	6_542_671_467	6_507_908_597	+34_762_870	+0.53%	✅
alloc-121392	17_169_247_360	17_134_416_241	+34_831_119	+0.20%	✅
alloc-317810	43_906_557_135	43_871_725_854	+34_831_281	+0.08%	✅
counter_sync	694_717_466	665_515_676	+29_201_790	+4.39%	⚠️
counter_async	864_744_780	837_190_903	+27_553_877	+3.29%	⚠️
cross_program	2_389_919_866	2_393_184_894	-3_265_028	-0.14%	✅
redirect	3_475_129_383	3_425_067_798	+50_061_585	+1.46%	⚠️
stack_0	797_339_281	778_805_232	+18_534_049	+2.38%	⚠️
stack_1	3_773_636_581	3_693_170_602	+80_465_979	+2.18%	⚠️
stack_5	15_719_684_415	15_391_130_019	+328_554_396	+2.13%	⚠️
stack_10	29_507_480_522	28_866_676_553	+640_803_969	+2.22%	⚠️
stack_20	66_272_830_952	64_389_067_225	+1_883_763_727	+2.93%	⚠️

Legend

• 🚀 Significant improvement (>5% reduction)
• 👍 Minor improvement (<5% reduction)
• ✅ No significant change
• ⚠️ Minor regression (<5% increase)
• ❌ Significant regression (>5% increase)

---

_{🤖 This comment was automatically generated by the benchmark comparison workflow at 62b8a73.}

[github-actions]

🔬 Benchmark Comparison

Benchmark	Current	Baseline	Change	Change %	Status
compute	465_522_069_624	465_485_012_100	+37_057_524	+0.01%	✅
alloc-0	596_675_244	561_979_259	+34_695_985	+6.17%	❌
alloc-12	600_245_331	565_520_788	+34_724_543	+6.14%	❌
alloc-143	760_059_042	725_298_850	+34_760_192	+4.79%	⚠️
alloc-986	863_050_736	828_290_220	+34_760_516	+4.20%	⚠️
alloc-10945	2_217_292_379	2_042_673_536	+174_618_843	+8.55%	❌
alloc-46367	6_542_669_761	6_507_908_597	+34_761_164	+0.53%	✅
alloc-121392	17_169_245_654	17_134_416_241	+34_829_413	+0.20%	✅
alloc-317810	43_906_555_429	43_871_725_854	+34_829_575	+0.08%	✅
counter_sync	694_717_466	665_515_676	+29_201_790	+4.39%	⚠️
counter_async	864_744_780	837_190_903	+27_553_877	+3.29%	⚠️
cross_program	2_389_919_866	2_393_184_894	-3_265_028	-0.14%	✅
redirect	3_475_129_383	3_425_067_798	+50_061_585	+1.46%	⚠️
stack_0	797_337_575	778_805_232	+18_532_343	+2.38%	⚠️
stack_1	3_773_629_757	3_693_170_602	+80_459_155	+2.18%	⚠️
stack_5	15_719_657_119	15_391_130_019	+328_527_100	+2.13%	⚠️
stack_10	29_507_427_636	28_866_676_553	+640_751_083	+2.22%	⚠️
stack_20	66_272_726_886	64_389_067_225	+1_883_659_661	+2.93%	⚠️

Legend

• 🚀 Significant improvement (>5% reduction)
• 👍 Minor improvement (<5% reduction)
• ✅ No significant change
• ⚠️ Minor regression (<5% increase)
• ❌ Significant regression (>5% increase)

---

_{🤖 This comment was automatically generated by the benchmark comparison workflow at f0ac4e5.}