Add @Namespace for GraphQLApi and GraphQLClientApi #2184

RoMiRoSSaN · 2024-09-06T10:08:49Z

This PR is only open to see what changes may be needed to changes suggestion by @t1 from this discussion #2173.
For viewing only, not for merge.

t1

I like it!

Most of the changes are not from the @Name → @Namespace change, but from using "namespace" instead of "group" and the fact that they can be nested.

t1 · 2024-09-06T10:16:26Z

client/implementation/src/main/java/io/smallrye/graphql/client/impl/typesafe/QueryBuilder.java

-        request.append(method.getName());
-        if (method.hasValueParameters())
+
+        request.append(method.getOperationName()); // operation name


Suggested change

request.append(method.getOperationName()); // operation name

request.append(method.getOperationName());

t1 · 2024-09-06T10:20:15Z

client/implementation/src/main/java/io/smallrye/graphql/client/impl/typesafe/QueryBuilder.java

+        if (!namespaces.isEmpty()) {
+            namespaces.forEach(value -> {
+                request.append(" { ");
+                request.append(value);
+            });
        }


Suggested change

if (!namespaces.isEmpty()) {

namespaces.forEach(value -> {

request.append(" { ");

request.append(value);

});

}

namespaces.forEach(namespace -> request.append(" { ").append(namespace)});

t1 · 2024-09-06T10:28:20Z

...tion/src/main/java/io/smallrye/graphql/client/impl/typesafe/reflection/MethodInvocation.java

+    }
+
+    public String getOperationName() {
+        return namespaces.stream().map(this::prettyString).collect(joining()) + prettyString(getName());


I'm not sure about this. Why do we do this? And if we wouldn't uppercase the very first character, most changes to the tests would become unnecessary.

For example

@Namespace("first/second/third/someMynotherName") class Api { @Query("findAll") //// }

If don create first letter to upper case, operation will firstsecondthirdsomeMynotherNamefindAll. it is unreadable.
And create it only findAll incorrect, becouse in code may be other findAll method. And if we will call just findAll, using some router (with analytics), it can break call analytics.

Okay, I think I get it: if the user wants to send multiple operations in one request, their names have to be distinct. But with the typesafe client, you can send multiple request only with a @Multiple annotation. The operation name is only scoped within a query string, not globally. I think we can safely skip this. Try to write a test to prove me wrong 😜
BTW, this code does uppercase the very first letter: FirstSecondThirdSomeMynotherName ... but the F could also remain f 😁

When the Quarkus tests failed, I saw that Quarkus also checks the operation name.
And maybe it’s worth making sure that the operation name is formed like this:

If there is @Name or @Namespace, capitalize the first letters.

If not, leave it as is.

As a result, the quarkus build will not crash, and there will be a minimum changes in the tests.
As for @Multiple, I'll take a look today.

I'm obviously biased by the Java naming convention that methods start with a lowercase character. That's why I'd like to stick with that, also for operation names. I.e., also if there is a @Namespace annotation, the very first character should be lowercase. E.g., @Namespace("users") ... @Query List<User> all() {... would result in an operation name usersAll.

I just referred to examples from the graphql documentation https://graphql.org/learn/queries/#operation-name
But of course I can change it to your example, no problem.

t1 · 2024-09-06T10:32:39Z

client/model-builder/src/main/java/io/smallrye/graphql/client/model/QueryBuilder.java

@@ -34,15 +36,19 @@ public QueryBuilder(MethodInfo method) {
    public String build() {
        StringBuilder request = new StringBuilder(method.getOperationTypeAsString());
        request.append(" ");
-        request.append(method.getName()); // operationName
+
+        request.append(method.getOperationName()); // operation name


Suggested change

request.append(method.getOperationName()); // operation name

request.append(method.getOperationName());

t1 · 2024-09-06T10:35:51Z

client/model-builder/src/main/java/io/smallrye/graphql/client/model/QueryBuilder.java

+        List<String> namespaces = method.getNamespaces();
+        if (!namespaces.isEmpty()) {
+            namespaces.forEach(value -> {
+                request.append(" { ");
+                request.append(value);
+            });


Same as in the QueryBuilder.

I really look forward to get rid of this kind of code duplication when @mskacelik finishes his work.

t1 · 2024-09-07T06:20:59Z

server/api/src/main/java/io/smallrye/graphql/api/Namespace.java

+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.TYPE })
+@Documented
+@Experimental("Experimental namespaces on api class. Separate namespaces via '/' (example - admin/users)")


I would move the second sentence into Javadoc. And add a hint that the class name is being used as the default value.

t1 · 2024-09-07T06:25:12Z

server/implementation/src/main/java/io/smallrye/graphql/bootstrap/Bootstrap.java

+        return value.substring(0, 1).toUpperCase() + value.substring(1);
+    }
+
+    private void addNamespacedRootObject(GraphQLObjectType.Builder mutationBuilder,


The parameters can also be for queries, can't they? Maybe better rename it to, e.g., operationBuilder/namespaceOperations/operationType?

t1 · 2024-09-07T06:30:03Z

server/implementation/src/main/java/io/smallrye/graphql/bootstrap/Bootstrap.java


-            GraphQLObjectType namedType = createNamedType(rootName, group, operations);
+        if (!groupContainer.getOperations().isEmpty() || !graphQLFieldDefinitions.isEmpty()) {


Suggested change

if (!groupContainer.getOperations().isEmpty() || !graphQLFieldDefinitions.isEmpty()) {

if (groupContainer.getOperations().isEmpty() && graphQLFieldDefinitions.isEmpty()) {

return List.of();

}

t1 · 2024-09-07T06:34:16Z

server/implementation/src/main/java/io/smallrye/graphql/bootstrap/Bootstrap.java

            objectTypeBuilder = objectTypeBuilder.field(graphQLFieldDefinition);
        }

+        objectTypeBuilder.fields(graphQLFieldDefinitions);


isn't the second one unnecessary?

here passed nested objects.
@Namespace("admin"), @Namespace("admin/users"). Each contains some operations. Here builds admin definition (with its opeartions), and in the next adds definitions 'users' and etc..

t1 · 2024-09-07T06:35:41Z

.../implementation/src/test/java/io/smallrye/graphql/test/namespace/SourceNamespaceTestApi.java


 @GraphQLApi
+@Namespace("first/second")


This is so much nicer! 😁

RoMiRoSSaN · 2024-09-09T11:37:53Z

I don't like it in this form yet. I think it would be better to roll back the changes. And expand the existing code. To enable work with Namespace, you need to add a config to switch to working with them. And by default, use what is there. With this approach, Quarkus will not break. And it will be possible to refine it (add additional configs, checks) without any problems.

I will rewrite it

t1 · 2024-09-12T05:52:12Z

I just wanted to repeat it: thanks, @RoMiRoSSaN. You're doing a great job!

RoMiRoSSaN · 2024-09-12T10:29:51Z

Hi, @t1

Summary at this moment

You can use @Name or @Namepace on the server and client code.
If both annotations are used - an error.
Needs simple changes in quarkus (add namesapced operations here)

I only have a question about the operation names. Quarkus tests fails on the check operation name. How should it be done?
Doing it by name is not correct if there are namespaces. I made the first letter capitalize. I had to make some minor changes to the tests. Now I think it makes sense to put this back for situations where there are no namespaces. And Quarkus tests will not fail, and there are fewer internal tests to edit.

@Namespace("fisrt/second")
@GraphQLClientApi
interface Api {
   @Query
   String get();  // Operation name will be 'FirstSecondGet'
}

@Name("fisrt")
@GraphQLClientApi
interface Api {
   @Query
   String get();  // Operation name will be 'FirstGet'
}

@GraphQLClientApi
interface Api {
   @Query
   String get();  // Operation name will be 'get'
}

And I'm waiting for your questions and suggestions

RoMiRoSSaN · 2024-09-12T13:43:50Z

@jmartisk Please, look at this later too. When you have time

t1 · 2024-09-17T07:43:44Z

If we would follow my comment above, the names would be firstSecondGet, firstGet, and get.

jmartisk · 2024-09-18T05:18:03Z

...c/main/java/io/smallrye/graphql/client/vertx/typesafe/VertxTypesafeGraphQLClientBuilder.java

@@ -185,7 +195,8 @@ public <T> T build(Class<T> apiClass) {
                endpoint,
                websocketUrl, executeSingleOperationsOverWebsocket, httpClient, webClient, subprotocols,
                websocketInitializationTimeout,
-                allowUnexpectedResponseFields);
+                allowUnexpectedResponseFields,
+                namespaceAnnotation != null);


Why would you pass a useNamespace boolean when you have already looked at the annotation and can now already just pass the information about the particular namespace as a List<String>? That would avoid having to use reflection later on.

client/model-builder/src/test/java/io/smallrye/graphql/client/model/ClientModelBuilderTest.java

jmartisk · 2024-09-18T05:24:42Z

...c/main/java/io/smallrye/graphql/client/vertx/typesafe/VertxTypesafeGraphQLClientBuilder.java

+
+        if (nameAnnotation != null && namespaceAnnotation != null) {
+            throw new RuntimeException("You can only use one of the annotations - @Name or @Namespace " +
+                    "over the GraphQLClientApi interface. Please, fix next interface: " + apiClass.getName());


Suggested change

"over the GraphQLClientApi interface. Please, fix next interface: " + apiClass.getName());

"over the GraphQLClientApi interface. Please, fix the interface: " + apiClass.getName());

jmartisk · 2024-09-18T05:42:01Z

common/schema-builder/src/main/java/io/smallrye/graphql/schema/SchemaBuilder.java

+        if (!errors.isEmpty()) {
+            throw new RuntimeException("Subscriptions can't be nested. " +
+                    "Move your subscriptions to another @GraphQLApi class, not marked @Namespace or @Name. " +
+                    "Check next places: " + String.join("; ", errors));


Suggested change

"Check next places: " + String.join("; ", errors));

"Check these places: " + String.join("; ", errors));

RoMiRoSSaN · 2024-09-19T17:07:27Z

@jmartisk
Replaced the string with an array of strings. As a result, it was possible to remove the code for groups and other things without any problems.
Good point about useNamespace, I've rollback it.
Managed to maintain backward compatibility with @Name
I checked these changes in quarkus - minor edits will be required.

It might be worth adding a check that the strings in @Name and @Namespace match some pattern (letters and strings, no spaces or symbols), and throw an exception. Or is it redundant? And fix docs.

jmartisk · 2024-09-20T06:24:51Z

client/model-builder/src/main/java/io/smallrye/graphql/client/model/ClientModelBuilder.java

+                .collect(Collectors.toList());
+        if (!errorInterfaces.isEmpty()) {
+            throw new RuntimeException("You can only use one of the annotations - @Name or @Namespace " +
+                    "over the GraphQLClientApi interface. Please, fix next interfaces: " +


Suggested change

"over the GraphQLClientApi interface. Please, fix next interfaces: " +

"over the GraphQLClientApi interface. Please, fix the following interfaces: " +

jmartisk · 2024-09-20T06:25:16Z

client/model-builder/src/main/java/io/smallrye/graphql/client/model/ClientModelBuilder.java

@@ -75,6 +80,19 @@ private ClientModels generateClientModels() {
        return clientModels;
    }

+    private void validateAnnotations(Collection<AnnotationInstance> graphQLApiAnnotations) {


Could we name this validateNamespaceAnnotations to make it more clear what it does?

jmartisk · 2024-09-20T06:30:08Z

Have you got a branch with the planned Quarkus-side changes too so that I can have a look?

RoMiRoSSaN · 2024-09-22T22:41:04Z

@jmartisk Hi. Here are the changes with comments. They are minimal. The main thing is to remove group processing.
Just in case - works without adding @Namesapce to the index and processing operations. I checked this in the native assembly. But most likely you should add these lines (subtleties of native assemblies, probably)

quarkusio/quarkus@bda9a2f

jmartisk · 2024-09-23T08:40:48Z

Yeah let's put the @Namespace annotation into the index to be sure,
and also the classes.addAll(getOperationClassNames(schema.getAllOperations())) call - I'm not sure what exactly you checked, but it should be necessary, at minimum in cases where GraphQL APIs work with non-scalar classes, I think. We need to make sure that the classes are registered for reflection.
If you could update your Quarkus commit per these comments, I would cherry-pick it and create a Quarkus branch that contains it, so we can later switch the CI (the "Quarkus tests" job) to run against that branch and get a full test run

RoMiRoSSaN · 2024-09-23T10:43:15Z

Please, check https://github.com/RoMiRoSSaN/quarkus/tree/namespaces

jmartisk · 2024-09-23T10:52:06Z

@RoMiRoSSaN I took the liberty to copy it into my own branch: https://github.com/jmartisk/quarkus/tree/smallrye-graphql-2.11 this branch will serve to capture any necessary changes that we will do in Quarkus along with upgrading to SmallRye GraphQL 2.11 (when it's released). I've also pushed a commit here to change the CI build so that the Quarkus part of the CI runs with a snapshot from that branch - so it should reflect the Quarkus-side changes. Let's see what the CI says now (it should fully pass now)

RoMiRoSSaN · 2024-09-23T11:37:38Z

Everything seems to be fine.
Please, if you are ready to accept this, look carefully at the changes again, I am ready to accept all comments.
And may be need to add more tests in quarkus for this

jmartisk · 2024-09-24T08:44:37Z

Ok I think this is pretty much good to go. @RoMiRoSSaN please mark it as ready if you agree

jmartisk · 2024-09-26T08:58:01Z

I've rebased it and squashed some commits, let's run the CI one more time

jmartisk · 2024-09-26T11:50:57Z

Thanks!

RoMiRoSSaN mentioned this pull request Sep 6, 2024

Graphql namespaces #2173

Closed

t1 approved these changes Sep 7, 2024

View reviewed changes

RoMiRoSSaN changed the title ~~[DRAFT] Replace using @Name to @Namespace on GraphQLApi and GraphQLClientApi~~ Add @Namespace for GraphQLApi and GraphQLClientApi Sep 12, 2024

RoMiRoSSaN marked this pull request as ready for review September 12, 2024 12:49

jmartisk reviewed Sep 18, 2024

View reviewed changes

client/model-builder/src/test/java/io/smallrye/graphql/client/model/ClientModelBuilderTest.java Outdated Show resolved Hide resolved

jmartisk reviewed Sep 18, 2024

View reviewed changes

RoMiRoSSaN marked this pull request as draft September 19, 2024 17:08

RoMiRoSSaN mentioned this pull request Sep 19, 2024

Handling federation _entities queries without creating @Query #2180

Merged

jmartisk reviewed Sep 20, 2024

View reviewed changes

RoMiRoSSaN marked this pull request as ready for review September 24, 2024 09:35

RoMiRoSSaN requested a review from a team as a code owner September 24, 2024 09:35

jmartisk previously approved these changes Sep 26, 2024

View reviewed changes

jmartisk dismissed their stale review via c647a51 September 26, 2024 08:57

jmartisk force-pushed the namespace branch from 80c9496 to c647a51 Compare September 26, 2024 08:57

Roman Lovakov and others added 2 commits September 26, 2024 11:19

Replace using @name to @namespace on GraphQLApi and GraphQLClientApi

ff3b3bd

Switch CI to custom branch for 2.11

1edb2ea

jmartisk force-pushed the namespace branch from c647a51 to 1edb2ea Compare September 26, 2024 09:19

jmartisk merged commit 485dc50 into smallrye:main Sep 26, 2024
5 checks passed

RoMiRoSSaN deleted the namespace branch September 26, 2024 20:23

	request.append(method.getOperationName()); // operation name
	request.append(method.getOperationName());


		GraphQLObjectType namedType = createNamedType(rootName, group, operations);
		if (!groupContainer.getOperations().isEmpty() \|\| !graphQLFieldDefinitions.isEmpty()) {

-        if (!groupContainer.getOperations().isEmpty() || !graphQLFieldDefinitions.isEmpty()) {
+        if (groupContainer.getOperations().isEmpty() && graphQLFieldDefinitions.isEmpty()) {
+            return List.of();
+        }

	"over the GraphQLClientApi interface. Please, fix next interface: " + apiClass.getName());
	"over the GraphQLClientApi interface. Please, fix the interface: " + apiClass.getName());

	"Check next places: " + String.join("; ", errors));
	"Check these places: " + String.join("; ", errors));


		@GraphQLApi
		@Namespace("first/second")

Add @Namespace for GraphQLApi and GraphQLClientApi #2184

Add @Namespace for GraphQLApi and GraphQLClientApi #2184

Conversation

RoMiRoSSaN commented Sep 6, 2024

t1 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

RoMiRoSSaN commented Sep 9, 2024 • edited Loading

t1 commented Sep 12, 2024

RoMiRoSSaN commented Sep 12, 2024 • edited Loading

RoMiRoSSaN commented Sep 12, 2024

t1 commented Sep 17, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

RoMiRoSSaN commented Sep 19, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jmartisk commented Sep 20, 2024

RoMiRoSSaN commented Sep 22, 2024

jmartisk commented Sep 23, 2024

RoMiRoSSaN commented Sep 23, 2024

jmartisk commented Sep 23, 2024 • edited Loading

RoMiRoSSaN commented Sep 23, 2024 • edited Loading

jmartisk commented Sep 24, 2024

jmartisk commented Sep 26, 2024

jmartisk commented Sep 26, 2024

RoMiRoSSaN commented Sep 9, 2024 •

edited

Loading

RoMiRoSSaN commented Sep 12, 2024 •

edited

Loading

RoMiRoSSaN commented Sep 19, 2024 •

edited

Loading

jmartisk commented Sep 23, 2024 •

edited

Loading

RoMiRoSSaN commented Sep 23, 2024 •

edited

Loading