feat(extensions): Add extensions support #2634

karatakis · 2024-08-09T08:42:59Z

Summary:
Modify Tailcall to allow users to create a version with custom extension functionality. We achieve that by providing a @extension directive and an extension trait that developers must implement on their custom extensions before tailcall can load them. An example that showcases the power of extensions is included.

Issue Reference(s):
Fixes #2613

Build & Testing:
To test it run the following command cargo run -p extension-i18n and execute the query

{
  user(id: 1) {
    id
    name
    company {
      catchPhrase
    }
  }
}

I ran cargo test successfully.
I have run ./lint.sh --mode=fix to fix all linting issues raised by ./lint.sh --mode=check.

Checklist:

I have added relevant unit & integration tests.
I have updated the documentation accordingly.
I have performed a self-review of my code.
PR follows the naming convention of <type>(<optional scope>): <title>

codecov · 2024-08-09T08:51:10Z

Codecov Report

Attention: Patch coverage is 83.60656% with 10 lines in your changes missing coverage. Please review.

Project coverage is 86.47%. Comparing base (5faf008) to head (656255d).
Report is 145 commits behind head on main.

Files with missing lines	Patch %	Lines
src/core/blueprint/operators/extension.rs	80.00%	9 Missing ⚠️
src/core/config/config.rs	50.00%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2634   +/-   ##
=======================================
  Coverage   86.46%   86.47%           
=======================================
  Files         255      256    +1     
  Lines       24963    25022   +59     
=======================================
+ Hits        21584    21637   +53     
- Misses       3379     3385    +6

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

examples/extension-i18n/src/main.rs

src/core/blueprint/operators/extension.rs

src/core/ir/eval.rs

src/core/ir/model.rs

src/core/ir/eval.rs

src/core/blueprint/operators/extension.rs

examples/extension-i18n/src/main.rs

examples/extension-i18n/main.graphql

Co-authored-by: Kiryl Mialeshka <[email protected]>

src/core/blueprint/operators/extension.rs

examples/extension-i18n/src/main.rs

src/core/config/config.rs

karatakis · 2024-08-19T10:42:23Z

RFC:

The current Extension SDK implementation exposes the user to Tailcall internal API structs, which are subject to change in the future.

#[async_trait::async_trait]
pub trait ExtensionTrait<Json: JsonLikeOwned>: std::fmt::Debug + Send + Sync {
    fn load(&self) {}

    async fn prepare(&self, context: PrepareContext<Json>) -> Box<IR>;

    async fn process(&self, context: ProcessContext<Json>) -> Result<Json, Error>;
}

To solve this issue, I suggest we create new enumerations, PrepareOperation and ProcessOperation, which give a set of pre-defined operations for the Extension SDK user. Those enums follow a similar logic to IR but provide a subset of operations the user can safely use. At the same time, the development team will enforce the rule that it is always backward compatible.

Proposed solution:

#[async_trait::async_trait]
pub trait ExtensionTrait<Json: JsonLikeOwned>: std::fmt::Debug + Send + Sync {
    fn load(&self) {}

    async fn prepare_steps(&self) -> Box<PrepareOperation>;

    async fn process(&self) -> Box<ProcessOperation>;
}

pub enum PrepareOperation {
  ModifyRequestHeaders(HashMap<String, String>),
  AddRequestCookie(String),
  // TODO add other operations
  Compose(Box<PrepareOperation>, Box<PrepareOperation>),
}

pub enum ProcessOperation {
  ExtractPath(Vec<String>),
  ModifyValue(Fn(ProcessContext<Json>) -> Result<Json>),
  GroupBy(Vec<String>),
  Filter(Vec<String>, Fn(JsonLike) -> bool),
  // TODO add other operations
  Compose(Box<ProcessOperation>, Box<ProcessOperation>),

The design is not final, and it is open to suggestions

meskill · 2024-08-22T09:46:24Z

RFC:

Have you considered a middleware pattern for this? This be could be more ergonomic and familiar for users.

Something like this:

#[async_trait::async_trait]
pub trait ExtensionTrait<Json: JsonLikeOwned>: std::fmt::Debug + Send + Sync {
    fn load(&self) {}

    async fn execute(&self, context: Context<Json>) -> Result<Json, Error> {
        context.set_cookie(...);
        context.set_headers(...);
        let response = context.http(...).await;
        convert_response(response)
    }
}

karatakis · 2024-08-23T05:19:33Z

@meskill, that's a good idea. I agree with you that more people will be comfortable with the middleware approach.

github-actions · 2024-08-28T06:03:52Z