Some Basic Questions

[TheServerAsterisk]

I have few questions many of them are more so due to the fact I having some difficulty flowing the flow of the crate.

1. How do arguments work and how do I parse them?

For example, the graphql docs gives the example

query DroidById($id: ID!) {
  droid(id: $id) {
    name
  }
}
{
   id: [1,2] // lets pretend r2d2 and 3cpo are id 1 and 2 
}

I can see that there is an argument struct so would I pass them in like so?

graphql_object!(<'a> &'a Droid: Database as "Droid" |&self| {
    description: "A mechanical creature in the Star Wars universe."

    interfaces: [&Character]

    field id(id: juniper::Arguments) -> &str as "The id of the droid" {
        self.id()
    }
...

Given a list of the above do I have expose two different Query Roots? One for Droids and the other Driod? That is, if we changed the Query root to

graphql_object!(Database: Database as "Query" |&self| {
    ...
    field droid(
        id: String as "id of the droid"
    ) -> Option<&Vec<Droid>> {
        self.get_droid(&id)
    }
 ...

Which I guess would work if the get_droid method returned Option<&Vec> and rustc would serialize it.

My apologies for these basic questions, but it just not clicking for me. 😞

[TheServerAsterisk]

Also, I know this part of the of the road 1.0 map, but how is the context factory utilized?

[mhallin]

Hello!

field is intended to work like the regular fn, so you write arguments for GraphQL just like you would for regular Rust functions. Juniper will take care of parsing, validation, and type conversion automatically.

So, if you have this query:

query DroidById($id: ID!) {
  droid(id: $id) {
    name
  }
}

A corresponding Rust schema could look like

struct Database {
    droids: HashMap<String, Droid>
}

graphql_object!(Database: Database as "Query" |&self| {
    field droid(id: String) -> Option<&Droid> {
        self.droids.get(&id)
    }
});

struct Droid {
    id: String,
    name: String,
}

graphql_object!(Droid: Database as "Droid" |&self| {
    field id() -> &str {
        &self.id
    }

    field name() -> &str {
        &self.name
    }
});

[mhallin]

The StarWars test schema is a fairly full-featured example that shows off a lot of features, but for getting started it's a bit complicated; especially with interfaces and lifetimes.

If you have more questions, feel free to ask them :) I hope to write better documentation and introduction guides than what I currently have.

[TheServerAsterisk]

@mhallin I am curious as to why one is not allowed to a mutable context? The main issue I am predominantly now dealing with a r2d2 PooledConnection Struct and the connection it exposes. So for example,

graphql_object!(QueryRoot: PooledConnection<MySqlConnectionManager> as "Query" |&self| {
        field droid(
        droid_id: String as "droid id",
        &mut executor
    ) -> Option<&Droid> {
        let conn =  executor.context();
        conn.prep_exec(SELECT * FROM Droid WHERE id = :id);  //fails here
    }
}

Since context() return a borrowed reference it is difficult to use a database connection. As far as I can tell the mysql and postgres crates require you to have read and write to the struct in question in order to use it.

[mhallin]

Allowing a mutable context would unfortunately affect all use cases where you don't need a mutable context. I've got an update on the master branch that makes &mut executor simply &executor which in turn will allow parallel query execution and maybe integration into Tokio or Futures.

In this case, I would suggest using interior mutability e.g. through RefCell or RWLock. I'm using PostgresConnectionManager in another projects, which supports querying and creating transactions without requiring a mutable reference.

[TheServerAsterisk]

@mhallin Thank you for answer my question so far. I think I have everything mostly figured out. However, I want to make sure whether this is correct or not. Is it a best practice to have the FiedlResult borrow the data as suggested by the examples or does it really matter or is there something written so that it will "magically" borrow the data?

[mhallin]

These field "functions" are executed roughly as if they were regular Rust functions. Therefore, returning a borrowed or owned reference depends on where you get the data from. If you construct it -e.g. by querying a database or concatenating strings - you will have to return an owned reference since it's a temporary value that can't be borrowed. However, if you return a struct field from self or the context then it's better to return a borrowed value than cloning it.

For example, see how these two examples differ:

struct QueryRoot;

struct User {
    username: String,
}

graphql_object!(QueryRoot: Database as "Query" |&self| {
    // The database layer would execute SQL and return a *new* User instance,
    // so we can't return a borrowed reference to this user.
    field registerUser(&mut executor, username: String) -> Option<User> {
        executor.context().user_by_username(username)
    }
});

graphql_object!(User: Database as "User" |&self| {
    // Here, we can return a borrowed reference since &self will outlive field resolution.
    // If we chose to return "String" here, we would have to clone the value, causing
    // extra allocations.
    field username() -> &String {
        &self.username
    }
});

I hope this answers your questions :) I'm trying to nail down the API to something that has a good mix between "magic" and something that can be understood so these questions are great for driving the design!

[TheServerAsterisk]

@mhallin Is it possible to make the input object public? Or is it the case I am misunderstanding something and this a bad idea?

For example in one file one might have:

use model::droid::MutDroid; 

pub struct MutRoot; 

graphql_object!(MutRoot: DbConn) { 
     field droid(droid: MutDroid)  {
          Droid::to_database(); // magically does the sql stuff 
    }
}

and in a different file

graphql_input_object!(
    pub  struct MutDroid as "Droid" { /// this doesn't work as it is not expecting the pub token
        ... 
    } 
);

[mhallin]

No, that is an oversight on my part in the macro syntax. I'll push a fix for that.