ci: add formatting CI (GoogleCloudPlatform#122)

* ci: add formatting CI

Use Google formatting guidelines to format existing code.

* Merge with lint workflow and add formatting instructions to CONTRIBUTING.md

Author: anniefu

.github/workflows/lint.yaml

@@ -4,6 +4,7 @@ on:
     branches:
     - master
   pull_request:
+  workflow_dispatch:
 jobs:
   lint:
     runs-on: ubuntu-latest
@@ -20,4 +21,20 @@ jobs:
     - name: Build Invoker with Maven
       run: (cd functions-framework-api/ && mvn install)
     - name: Lint Invoker
-      run: (cd invoker/ && mvn clean verify -DskipTests -P lint)
+      run: (cd invoker/ && mvn clean verify -DskipTests -P lint)
+  formatting:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2 # v2 minimum required
+      - name: Run formatter
+        id: formatter
+        uses: axel-op/googlejavaformat-action@v3
+        with:
+          args: "--dry-run --set-exit-if-changed"
+        continue-on-error: true
+      - name: Check for failure
+        if: steps.formatter.outcome != 'success'
+        run: |
+          echo "Java format check failed, see 'Run formatter' step for more information."
+          echo "See https://github.com/google/google-java-format for options on running the formatter locally."
+          exit 1

.github/workflows/unit.yaml

@@ -1,5 +1,9 @@
 name: Java Unit CI
-on: [push, pull_request]
+on:
+  push:
+    branches:
+    - master
+  pull_request:
 jobs:
   build:
     runs-on: ubuntu-latest

CONTRIBUTING.md

@@ -61,6 +61,11 @@ Install `mvn`:
 
 https://maven.apache.org/install.html
 
+### Formatting
+This repo follows the Google Java Style guide for formatting. You can setup the
+formatting tool locally using one of the options provided at
+[google/google-java-format](https://github.com/google/google-java-format#google-java-format).
+
 ## Install and Run Invoker Tests Locally
 
 ```

functions-framework-api/src/main/java/com/google/cloud/functions/BackgroundFunction.java

@@ -17,14 +17,14 @@
 /**
  * Represents a Cloud Function that is activated by an event and parsed into a user-supplied class.
  * The payload of the event is a JSON object, which is deserialized into a user-defined class as
- * described for
- * <a href="https://github.com/google/gson/blob/master/UserGuide.md#TOC-Object-Examples">Gson</a>.
- *
- * <p>Here is an example of an implementation that accesses the {@code messageId} property from
- * a payload that matches a user-defined {@code PubSubMessage} class:
+ * described for <a
+ * href="https://github.com/google/gson/blob/master/UserGuide.md#TOC-Object-Examples">Gson</a>.
  *
+ * <p>Here is an example of an implementation that accesses the {@code messageId} property from a
+ * payload that matches a user-defined {@code PubSubMessage} class:
  * <!-- The {@code} placement is a bit strange here, to prevent spurious spaces introduced by the
  *      javadoc tool. -->
+ *
  * <pre>
  * public class Example implements{@code BackgroundFunction<PubSubMessage>} {
  *   private static final Logger logger = Logger.getLogger(Example.class.getName());
@@ -49,9 +49,9 @@
 @FunctionalInterface
 public interface BackgroundFunction<T> {
   /**
-   * Called to service an incoming event. This interface is implemented by user code to
-   * provide the action for a given background function. If this method throws any exception
-   * (including any {@link Error}) then the HTTP response will have a 500 status code.
+   * Called to service an incoming event. This interface is implemented by user code to provide the
+   * action for a given background function. If this method throws any exception (including any
+   * {@link Error}) then the HTTP response will have a 500 status code.
    *
    * @param payload the payload of the event, deserialized from the original JSON string.
    * @param context the context of the event. This is a set of values that every event has,

functions-framework-api/src/main/java/com/google/cloud/functions/CloudEventsFunction.java

@@ -3,14 +3,15 @@
 import io.cloudevents.CloudEvent;
 
 /**
- * Represents a Cloud Function that is activated by an event and parsed into a {@link CloudEvent} object.
+ * Represents a Cloud Function that is activated by an event and parsed into a {@link CloudEvent}
+ * object.
  */
 @FunctionalInterface
 public interface CloudEventsFunction {
   /**
-   * Called to service an incoming event. This interface is implemented by user code to
-   * provide the action for a given background function. If this method throws any exception
-   * (including any {@link Error}) then the HTTP response will have a 500 status code.
+   * Called to service an incoming event. This interface is implemented by user code to provide the
+   * action for a given background function. If this method throws any exception (including any
+   * {@link Error}) then the HTTP response will have a 500 status code.
    *
    * @param event the event.
    * @throws Exception to produce a 500 status code in the HTTP response.

functions-framework-api/src/main/java/com/google/cloud/functions/Context.java

@@ -21,44 +21,44 @@
 public interface Context {
   /**
    * Returns event ID.
-   * 
+   *
    * @return event ID
    */
   String eventId();
 
   /**
    * Returns event timestamp.
-   * 
+   *
    * @return event timestamp
    */
   String timestamp();
 
   /**
    * Returns event type.
-   * 
+   *
    * @return event type
    */
   String eventType();
 
   /**
    * Returns event resource.
-   * 
+   *
    * @return event resource
    */
   String resource();
 
   /**
    * Returns additional attributes from this event. For CloudEvents, the entries in this map will
-   * include the
-   * <a href="https://github.com/cloudevents/spec/blob/v1.0/spec.md#required-attributes">required
-   * attributes</a> and may include
-   * <a href="https://github.com/cloudevents/spec/blob/v1.0/spec.md#required-attributes">optional
-   * attributes</a> and
-   * <a href="https://github.com/cloudevents/spec/blob/v1.0/spec.md#extension-context-attributes">
+   * include the <a
+   * href="https://github.com/cloudevents/spec/blob/v1.0/spec.md#required-attributes">required
+   * attributes</a> and may include <a
+   * href="https://github.com/cloudevents/spec/blob/v1.0/spec.md#required-attributes">optional
+   * attributes</a> and <a
+   * href="https://github.com/cloudevents/spec/blob/v1.0/spec.md#extension-context-attributes">
    * extension attributes</a>.
    *
-   * <p>The map returned by this method may be empty but is never null.</p>
-   * 
+   * <p>The map returned by this method may be empty but is never null.
+   *
    * @return additional attributes form this event.
    */
   default Map<String, String> attributes() {

functions-framework-api/src/main/java/com/google/cloud/functions/HttpFunction.java

@@ -14,9 +14,7 @@
 
 package com.google.cloud.functions;
 
-/**
- * Represents a Cloud Function that is activated by an HTTP request.
- */
+/** Represents a Cloud Function that is activated by an HTTP request. */
 @FunctionalInterface
 public interface HttpFunction {
   /**

functions-framework-api/src/main/java/com/google/cloud/functions/HttpMessage.java

@@ -21,9 +21,7 @@
 import java.util.Map;
 import java.util.Optional;
 
-/**
- * Represents an HTTP message, either an HTTP request or a part of a multipart HTTP request.
- */
+/** Represents an HTTP message, either an HTTP request or a part of a multipart HTTP request. */
 public interface HttpMessage {
   /**
    * Returns the value of the {@code Content-Type} header, if any.
@@ -40,19 +38,19 @@ public interface HttpMessage {
   long getContentLength();
 
   /**
-   * Returns the character encoding specified in the {@code Content-Type} header,
-   * or {@code Optional.empty()} if there is no {@code Content-Type} header or it does not have the
-   * {@code charset} parameter.
+   * Returns the character encoding specified in the {@code Content-Type} header, or {@code
+   * Optional.empty()} if there is no {@code Content-Type} header or it does not have the {@code
+   * charset} parameter.
    *
    * @return the character encoding for the content type, if one is specified.
    */
   Optional<String> getCharacterEncoding();
 
   /**
-   * Returns an {@link InputStream} that can be used to read the body of this HTTP request.
-   * Every call to this method on the same {@link HttpMessage} will return the same object.
-   * This method is typically used to read binary data. If the body is text, the
-   * {@link #getReader()} method is more appropriate.
+   * Returns an {@link InputStream} that can be used to read the body of this HTTP request. Every
+   * call to this method on the same {@link HttpMessage} will return the same object. This method is
+   * typically used to read binary data. If the body is text, the {@link #getReader()} method is
+   * more appropriate.
    *
    * @return an {@link InputStream} that can be used to read the body of this HTTP request.
    * @throws IOException if a valid {@link InputStream} cannot be returned for some reason.
@@ -72,8 +70,8 @@ public interface HttpMessage {
   BufferedReader getReader() throws IOException;
 
   /**
-   * Returns a map describing the headers of this HTTP request, or this part of a multipart
-   * request. If the headers look like this...
+   * Returns a map describing the headers of this HTTP request, or this part of a multipart request.
+   * If the headers look like this...
    *
    * <pre>
    *   Content-Type: text/plain
@@ -82,11 +80,11 @@ public interface HttpMessage {
    * </pre>
    *
    * ...then the returned value will map {@code "Content-Type"} to a one-element list containing
-   * {@code "text/plain"}, and {@code "Some-Header"} to a two-element list containing
-   * {@code "some value"} and {@code "another value"}.
+   * {@code "text/plain"}, and {@code "Some-Header"} to a two-element list containing {@code "some
+   * value"} and {@code "another value"}.
    *
-   * @return a map where each key is an HTTP header and the corresponding {@code List} value has
-   *     one element for each occurrence of that header.
+   * @return a map where each key is an HTTP header and the corresponding {@code List} value has one
+   *     element for each occurrence of that header.
    */
   Map<String, List<String>> getHeaders();
 
@@ -104,7 +102,6 @@ public interface HttpMessage {
    * and {@code getFirstHeader("Another-Header")} will return {@code Optional.empty()}.
    *
    * @param name an HTTP header name.
-   *
    * @return the first value of the given header, if present.
    */
   default Optional<String> getFirstHeader(String name) {

functions-framework-api/src/main/java/com/google/cloud/functions/HttpRequest.java

@@ -18,9 +18,7 @@
 import java.util.Map;
 import java.util.Optional;
 
-/**
- * Represents the contents of an HTTP request that is being serviced by a Cloud Function.
- */
+/** Represents the contents of an HTTP request that is being serviced by a Cloud Function. */
 public interface HttpRequest extends HttpMessage {
   /**
    * The HTTP method of this request, such as {@code "POST"} or {@code "GET"}.
@@ -37,39 +35,39 @@ public interface HttpRequest extends HttpMessage {
   String getUri();
 
   /**
-   * The path part of the URI for this request, without any query. If the full URI is
-   * {@code http://foo.com/bar/baz?this=that}, then this method will return {@code /bar/baz}.
+   * The path part of the URI for this request, without any query. If the full URI is {@code
+   * http://foo.com/bar/baz?this=that}, then this method will return {@code /bar/baz}.
    *
    * @return the path part of the URI for this request.
    */
   String getPath();
 
   /**
-   * The query part of the URI for this request. If the full URI is
-   * {@code http://foo.com/bar/baz?this=that}, then this method will return {@code this=that}.
-   * If there is no query part, the returned {@code Optional} is empty.
+   * The query part of the URI for this request. If the full URI is {@code
+   * http://foo.com/bar/baz?this=that}, then this method will return {@code this=that}. If there is
+   * no query part, the returned {@code Optional} is empty.
    *
    * @return the query part of the URI, if any.
    */
   Optional<String> getQuery();
 
   /**
-   * The query parameters of this request. If the full URI is
-   * {@code http://foo.com/bar?thing=thing1&thing=thing2&cat=hat}, then the returned map will map
-   * {@code thing} to the list {@code ["thing1", "thing2"]} and {@code cat} to the list with the
-   * single element {@code "hat"}.
+   * The query parameters of this request. If the full URI is {@code
+   * http://foo.com/bar?thing=thing1&thing=thing2&cat=hat}, then the returned map will map {@code
+   * thing} to the list {@code ["thing1", "thing2"]} and {@code cat} to the list with the single
+   * element {@code "hat"}.
    *
-   * @return a map where each key is the name of a query parameter and the corresponding
-   *     {@code List} value indicates every value that was associated with that name.
+   * @return a map where each key is the name of a query parameter and the corresponding {@code
+   *     List} value indicates every value that was associated with that name.
    */
   Map<String, List<String>> getQueryParameters();
 
   /**
-   * The first query parameter with the given name, if any. If the full URI is
-   * {@code http://foo.com/bar?thing=thing1&thing=thing2&cat=hat}, then
-   * {@code getFirstQueryParameter("thing")} will return {@code Optional.of("thing1")} and
-   * {@code getFirstQueryParameter("something")} will return {@code Optional.empty()}. This is a
-   * more convenient alternative to {@link #getQueryParameters}.
+   * The first query parameter with the given name, if any. If the full URI is {@code
+   * http://foo.com/bar?thing=thing1&thing=thing2&cat=hat}, then {@code
+   * getFirstQueryParameter("thing")} will return {@code Optional.of("thing1")} and {@code
+   * getFirstQueryParameter("something")} will return {@code Optional.empty()}. This is a more
+   * convenient alternative to {@link #getQueryParameters}.
    *
    * @param name a query parameter name.
    * @return the first query parameter value with the given name, if any.
@@ -102,8 +100,8 @@ interface HttpPart extends HttpMessage {
    * value.
    *
    * @return a map from part names to part contents.
-   * @throws IllegalStateException if the {@link #getContentType() content type} is not
-   *     {@code multipart/form-data}.
+   * @throws IllegalStateException if the {@link #getContentType() content type} is not {@code
+   *     multipart/form-data}.
    */
   Map<String, HttpPart> getParts();
 }