Server Integration & Deployment

The scratch Bookshelf has the modules bookshelf-shared, bookshelf-client (packaging gwt-app), bookshelf-server (a war that depends on the client’s WAR, so that Maven’s WAR plugin overlays the module directory onto the server’s static files) and, for this page, bookshelf-assets and bookshelf-boot, which are explained in the Spring Boot section. One reactor build produces everything:

Source: gwt-maven-plugin — Artifact handlers

The WAR of the server module (after mvn clean package) contains 50 files: 11,888,376 bytes uncompressed and 9,443,734 bytes as a WAR. With the 32-character hashes replaced by <hash> and equal names counted, it holds:

Source: GWT — Deploying

Run mvn clean package, not only mvn package: the overlay of the client’s WAR is copied into the server module’s target directory without removing files of earlier builds, and a build made after the client had been recompiled had twelve <hash>.cache.js files for six permutations, the other six being the previous build’s, which a deployment would then carry. The -deploy directory (not in the WAR) contains the rpcPolicyManifest/manifest.txt that maps each service to its policy file:

Source: GWT — FAQ Debugging and Compiling: The .gwt.rpc File

The two policy files list the types the server may serialise for each service, with one line per type (the type name, four flags, the type signature and a number); the Bookshelf’s lists Book, BookPage and BookNotFoundException for the catalog and XsrfToken and RpcTokenException for the token service. The GWT-RPC page explains the file format and the serialisation rules. For deployment only one fact matters: the server opens these files by name, and a server that cannot open them serialises less than you expect (see the pitfalls table).

The server-side RPC classes exist twice. The javax ones are in gwt-servlet, the Jakarta ones are in gwt-servlet-jakarta, in the package com.google.gwt.user.server.rpc.jakarta (verified in the 2.13.1 jar: RemoteServiceServlet, XsrfProtectedServiceServlet, XsrfTokenServiceServlet, RPC, RPCServletUtils). The client-side interfaces (RemoteService, AsyncCallback, XsrfProtectedService) are in the package com.google.gwt.user.client.rpc in both jars, so the shared code of an application does not change when the container does. The choice follows the servlet API of the container:

Source: Apache Tomcat — Which Version Do I Want?

Tomcat 10.0 implements the Servlet 5.0 API and is not covered by this page. Both artifacts are managed by the org.gwtproject:gwt BOM at 2.13.1, so the server module declares them without a version:

Source: GWT — Deploying: Deploying on a servlet container using RPC

The official guide still says to copy gwt-servlet.jar into war/WEB-INF/lib, which is the Ant-era instruction for the same thing; with Maven the dependency does it. The 2.11.0 release notes introduced the Jakarta artifacts.

When a browser sends an RPC request, the body names the module base URL and the strong name of the policy (see the captured request body in the section about prefixes). RemoteServiceServlet removes the context path from the path of the module base URL, appends the strong name and .gwt.rpc, and calls ServletContext.getResourceAsStream with the result. The 2.13.1 source states it in three branches, each with its own log message: the module path must start with the context path of the web application, the file must exist, and it must parse. If anything fails the servlet logs the error and falls back to a legacy 1.3.3-compatible policy, which allows far fewer types. Two consequences follow, and the rest of the page is largely about them:

Source: GWT source — RemoteServiceServlet.java (2.13.1)

On Tomcat the same WAR is deployed by copying it into the webapps directory, as the official guide’s Tomcat example does (the guide’s application then answers under /MyApp/, named after the WAR). A Tomcat installation was not run for this page. What the page did run is the embedded Tomcat 11.0.24 inside the Spring Boot jar below, with the same servlets and the same policy-file lookup, and a non-root context path (/shelf), which is the case that changes the module base URL. Use Tomcat 10.1 or 11 with gwt-servlet-jakarta; Tomcat 9 needs gwt-servlet and javax.servlet imports in the server classes.

The Developer Guide’s second example splits the traffic: Apache HTTPD serves everything except WEB-INF/ from its document root and proxies only the RPC URLs to Tomcat with ProxyPass and ProxyPassReverse, so that the browser sees a single origin. Its reason for deploying the entire WAR to Tomcat is the one found above: servlets may call ServletContext.getResource, and GWT-RPC servlets always need the generated policy file. The example’s check is still good practice: a GET of the RPC URL on both hosts should answer 405, and a 404 points at the left-hand side of the mapping while "Bad Gateway" points at the right-hand side. The Bookshelf shows the same 405 (the servlet only handles POST):

Source: GWT — Deploying RPC

A request that does reach the servlet but is not a GWT-RPC request is rejected by the servlet, which is what a firewall or proxy that rewrites the Content-Type produces:

Source: GWT source — RPCServletUtils.java (2.13.1)

A reverse proxy or an ingress that publishes the application under a prefix (/shelf/) and strips it before forwarding breaks the policy lookup, although the application itself looks healthy: the browser’s module base URL contains the prefix, the application’s context path does not, and the servlet then looks for /shelf/bookshelf/<hash>.gwt.rpc. The run below sends the real token request of the Bookshelf with the module base rewritten to such a path (the request body was captured from Chrome; only the first token changed):

Source: GWT source — RemoteServiceServlet.java (2.13.1)

The way to avoid it is to keep the prefix in the application: give the application the matching context path (Spring Boot: server.servlet.context-path=/shelf, which the Bookshelf was run with and which worked, because the servlet strips /shelf from the module path before it builds the file name) or do not strip the prefix in the proxy. When the policy files really live somewhere else, the servlet has a hook: the protected method doGetSerializationPolicy(HttpServletRequest, String moduleBaseURL, String strongName) of RemoteServiceServlet (the Jakarta variant has the same signature) is what the lookup calls, and overriding it is the supported way to load policies from another location. Overriding it widens what the server will deserialise, so the source of the policy must be as trusted as the application’s own WAR.

The first attempt copied the client’s WAR contents into target/classes/META-INF/resources of the Boot module (a maven-dependency-plugin unpack execution in prepare-package). The jar built, started, served every file and showed an empty catalog: the server log held the policy error of the first pitfall. The cause is the one in the second point above. Spring MVC found the files on the classpath and sent them to the browser, so bookshelf.nocache.js and the .gwt.rpc files all answered 200, but RemoteServiceServlet asks the servlet context, and the servlet context of the embedded Tomcat does not expose BOOT-INF/classes/META-INF/resources of an executable jar:

Source: Spring Boot — Static Content

(The same two lines, and the SerializationException that follows them, appear when the policy files are deleted from a deployed WAR; that run is in the pitfalls table.) The fix that needs no code is to package the module directory as the META-INF/resources of its own jar and make that jar a dependency of the application. The bookshelf-assets module does only that:

Source: Apache Maven Dependency Plugin — dependency:unpack

and the Boot module depends on it, on the server module’s classes (the WAR plugin’s attachClasses option produces the classes jar) and on nothing from the client:

Source: Spring Boot — Static Content

With that layout the jar (30,639,967 bytes, mostly Spring and the 9.6 MiB RPC jar) starts, the catalog loads and the log has no policy error. Both the server classes and the RPC library are on the classpath of the application, so nothing else is needed:

Source: Spring Boot — Embedded Web Servers

(The two lines are the result of loading / in headless Chrome and reading the page title and the visible text: the host page servlet answered, the module loaded, the XSRF token and the first catalog page came through RPC. The text is Spanish because the Chrome of the machine sends a Spanish Accept-Language, which the host page servlet honours.) With --server.servlet.context-path=/shelf the same jar served the same page at /shelf/, the module base URL became http://localhost:8936/shelf/bookshelf/ and the catalog loaded, with no policy error.

Spring Boot’s spring.web.resources.chain.strategy.content.enabled (content-hash version strategy) rewrites resource URLs that Spring generates in templates; it does nothing for GWT, whose file names are already hashes and are written into bookshelf.nocache.js by the compiler. The plain GET handlers of the other pages of the Spring Boot section (REST controllers, security, configuration) work next to these servlets unchanged; the starting points are Getting Started with Spring Boot, REST APIs with Spring MVC and WebFlux and Spring Security.

The client reads the data block and the meta tag in HostPage, with JSONParser.parseStrict (module com.google.gwt.json.JSON, which the User module does not include) and MetaElement; if the block is absent it falls back to the official article’s technique, Dictionary, which reads a global JavaScript object:

Source: GWT — Article: Dynamic Host Page, GWT source — Dictionary.java (2.13.1)

App.onModuleLoad calls HostPage.read() first and sets the document title to "Bookshelf - " + HostPage.user(). Chrome confirmed both paths: / (data block) gave the title Bookshelf - guest, and /inline.html, a static page that only has <script>var bookshelfInfo = { "user" : "inline-guest" };</script>, gave Bookshelf - inline-guest through Dictionary. A Dictionary name that is not defined throws MissingResourceException with the message Cannot find JavaScript object with the name 'bookshelfInfo', and one that is not an object throws '...' is not a JavaScript object and cannot be used as a Dictionary.

The article’s example writes the user’s e-mail address into the page as "email" : " followed by the raw value. With a value such as x</script><script>alert(1)</script> that closes the script element and starts another, so any value that comes from a user must be escaped for the context it is written into. For JSON in a script element that means escaping <, > and & (as <, >, &) and the two line separators U+2028 and U+2029, as well as the usual quote and backslash:

Source: GWT — Article: Dynamic Host Page

The unit test ScriptJsonTest (part of the 6 server tests that pass) prints what the two approaches write for the hostile value:

Source: GWT — Article: Dynamic Host Page

On the client side the data goes into the page with setText, never setHTML, and the SafeHtml & XSS page covers the cases where HTML must be built.

There are two kinds of token and they are not interchangeable.

The token is only as good as the session around it: the cookie flags (HttpOnly, Secure, SameSite) are container configuration. In this run Spring Boot’s Tomcat sent JSESSIONID=...; Path=/; HttpOnly and the Jetty plugin sent JSESSIONID=...; Path=/ without HttpOnly.

Because the hashed files never change under a name, a new release adds new names and leaves old ones unused. Three rules follow from that and from the policy-file lookup.

The module base URL is the URL of the script that was loaded. That has a consequence the CDN case runs into: if the host page loads http://localhost:8937/bookshelf/bookshelf.nocache.js from another origin, GWT.getModuleBaseURL() is that origin, and every RPC call is sent there. The run (host page on port 8936, a static file server with a copy of the module directory on port 8937):

Source: GWT source — ServiceDefTarget.java (2.13.1)

(The page loaded, the script ran and the title was set, which shows that the module can be loaded from another origin; only the RPC call failed.) There are two ways out, and the first is simpler:

The cloud sections of this site cover the storage and CDN products themselves. For the static half: S3 Security and Static Hosting with CloudFront and CDN Delivery, Cloud Storage Security and Static Sites with Cloud CDN and Media CDN, and Front Door and CDN. The rules to configure in all of them are the table above; most CDNs let a rule override the Cache-Control of the origin, and most can compress.

The compiled JavaScript is the largest file the user downloads, and it compresses well. Spring Boot compresses nothing by default; one property turns it on, and the mime types it compresses by default include text/javascript, application/javascript and text/css, the response must be at least 2 KB, and application/octet-stream (the type of the .gwt.rpc files) is not in the list. With --server.compression.enabled=true and Accept-Encoding: gzip the Bookshelf’s files shrank as follows:

Source: Spring Boot — Enable HTTP Response Compression

The equivalents elsewhere are documented by the containers: Tomcat’s HTTP connector has compression (on), compressibleMimeType (default text/html,text/xml,text/plain,text/css,text/javascript,application/javascript,application/json,application/xml) and compressionMinSize (default 2048 bytes), and Jetty has GzipHandler, a handler wrapper installed at server level with setMinGzipSize, setExcludedPaths and addIncludedMethods. Neither was run for this page. Two details are specific to GWT:

Source: Apache Tomcat 11 — HTTP Connector, Eclipse Jetty 12 — GzipHandler, GWT source — RemoteServiceServlet.java (2.13.1)

The upload servlet is the Jakarta Servlet Part API with the limits of <multipart-config>; no extra library is needed (the book’s servlet used the Apache Commons FileUpload library, which was the standard answer when the Servlet API had no multipart support). It does the five things every upload endpoint must do:

Source: OWASP — Unrestricted File Upload, OWASP — File Upload Cheat Sheet

The rules in that code, in the order of the cheat sheet’s own advice:

Not covered by the sample, and needed in production: virus scanning, re-encoding images so that a polyglot file is destroyed, per-user quotas and rate limits, and object storage instead of a local directory; the File Storage & Object Stores page covers the last.

The same two-file upload code ran under both containers, through curl and through Chrome’s file chooser (DevTools DOM.setFileInputFiles on the real FileUpload and a click on the real button):

Source: Jakarta Servlet 6.1 — MultipartConfigElement

With Spring Boot the limits of <multipart-config> go into the MultipartConfigElement of the ServletRegistrationBean (see upload() above), and they are the ones that apply to a raw servlet: the spring.servlet.multipart.* properties configure Spring MVC’s multipart resolver, not this registration. For files above a few megabytes the classic form has no progress bar and no resume. The browser APIs that offer progress (XMLHttpRequest with its upload object, and FormData with File) are in Elemental2 (elemental2.dom.XMLHttpRequest, XMLHttpRequestUpload, FormData and File exist in elemental2-dom 1.3.2) and need no server change, since the same multipart request reaches the same servlet; direct-to-object-storage uploads with pre-signed URLs take the file out of the application entirely.