From cb8375d46f9ba9b031246f96484571284e42c312 Mon Sep 17 00:00:00 2001
From: Pratham <pratham200209@gmail.com>
Date: Sun, 26 Jan 2025 18:01:54 +0530
Subject: [PATCH] chore: feature attemp doc for hurl parser
---
doc/feature_attempts/hurl.md | 65 ++++++++++++++++++++++++++++++++++++
1 file changed, 65 insertions(+)
create mode 100644 doc/feature_attempts/hurl.md
diff --git a/doc/feature_attempts/hurl.md b/doc/feature_attempts/hurl.md
new file mode 100644
index 00000000..0aa5dd8c
--- /dev/null
+++ b/doc/feature_attempts/hurl.md
@@ -0,0 +1,65 @@
+### Feature Implementation Writeup: HurlParser Wrapper for API Dash
+
+I initially started with the approach of writing my own parser using `petitparser` and creating a custom implementation. However, after about a week, the maintainer recommended against this approach. They highlighted that building a custom parser would lack future-proofing if `hurl.dev` were to implement changes. While I abandoned this route, the code is still available in a branch. My custom parser had progressed to the point where requests and assertions were working, though it was far from complete.
+
+#### Transition to Hurl Parser Wrapper Using Flutter Rust Bridge
+
+Following the maintainer's suggestion, I began developing a wrapper for the Hurl parser using `flutter_rust_bridge`. Since the documentation for the library can be sparse, I’ve documented my steps for clarity:
+
+1. **Creating the Library:**
+
+ - I ran the command:
+
+ `flutter_rust_bridge_codegen create hurl --template plugin`
+
+ - This initialized the project.
+2. **Adding the Parse Function:**
+
+ - I added the library code and the `parse_hurl` function in `rust/src/api/simple.rs`.
+3. **Generating the Flutter Side Code:**
+
+ - I ran:
+
+
+ `flutter_rust_bridge_codegen generate`
+
+ - This generated all the necessary code for Flutter and all the targeted platforms.
+
+`flutter_rust_bridge` uses a tool called `cargokit` to manage dependencies, acting as a glue layer between Flutter and Rust. Unfortunately, `cargokit` is still experimental, with little documentation available. The [blog post by Matej Knopp](https://matejknopp.com/post/flutter_plugin_in_rust_with_no_prebuilt_binaries/) provided valuable insights. One crucial takeaway was avoiding the Homebrew installation of Rust and instead using `rustup`. This resolved platform compilation issues for me, though the project is still not compiling entirely.
+
+#### Implementing the Wrapper
+
+I postponed multi-platform compilation issues to focus on writing the wrapper code. By reviewing the `hurl.dev` documentation and examples, I identified the required structure:
+
+- `HurlFile` → List of `Entries`
+- `Entries` → `Request` and `Response`
+
+Based on this, I created models in Dart using the `freezed` package. The goal was to convert the JSON output from the Hurl parser into Dart data models. I am confident this part turned out well.
+
+After writing tests for Hurl parsing and model generation, I shifted focus to building the project.
+
+#### Compilation Challenges
+
+During compilation, I encountered an issue, which I reported on the [Hurl repository](https://github.com/Orange-OpenSource/hurl/issues/3603). The Hurl parser depends on the `libxml2` crate for XML parsing. To resolve this, I had to add:
+
+`OTHER_LDFLAGS => -force_load ${BUILT_PRODUCTS_DIR}/libhurl.a -lxml2`
+
+This fixed the macOS build.
+
+However, testing on iOS and Android proved problematic, as I didn’t have access to Windows or Linux systems. For iOS, adding similar flags didn’t work. I tried various fixes, such as modifying the header search paths, linking frameworks, and changing build phases in Xcode, but none succeeded.
+
+#### Investigation into `libxml2`
+
+I learned that `libxml2` is not a system library but a crate that wraps platform-specific libraries. Unfortunately, `libxml2` does not support Android or iOS, causing persistent errors. After consulting the maintainers of Hurl and `flutter_rust_bridge`, I received the following suggestion from the Hurl maintainer:
+
+> _"I'm not an expert in iOS/Android, but what I would do is try to build something smaller, maybe just calling libxml through a Flutter component, then trying to build with libxml but with the Rust crate wrapper, etc."_ ([GitHub comment](https://github.com/Orange-OpenSource/hurl/issues/3603#issuecomment-2611159759))
+
+#### Current Status and Potential Solutions
+
+At this point, I’ve committed all my code to the repository in a fork. Here are some potential solutions I believe might work:
+
+1. **Use Dart Native FFIs**: Currently under an experimental flag, as suggested by the `flutter_rust_bridge` maintainer.
+2. **Revert to an Older Version of Hurlfmt**: Use a version of the library from before it transitioned to `libxml` for performance improvements.
+3. **Revisit My Custom Parser**: Complete the parser I started building with `petitparser`.
+
+If anyone knows a solution to these challenges or has suggestions, I’d appreciate the help!