se-gas-express

GasExpress - Express-like Router for Google Apps Scripts

GasExpress is a lightweight and easy-to-use library that provides an Express-like routing system for handling incoming HTTP requests in Google Apps Scripts. It allows you to define routes for POST and GET requests, add middleware functions for preprocessing requests, and handle responses efficiently.

Installation

To use GasExpress in your Google Apps Scripts project, you need to add the library to your project using the Library ID:

1. Open your Google Apps Scripts project.
2. Click on "Resources" in the top menu.
3. Select "Libraries" from the dropdown menu.
4. In the "Add a Library" field, enter the Library ID: 1QkUDMtLCsgnC2Zn05jlb8UYbj9KRgaljLfY-PvXs5JtYgE0MwAvMO1lx.
5. Click "Add."

Subpath Authorization Workaround

This implementation includes a workaround for the Google Apps Scripts (WebApp) deployment constraint regarding subpaths. Normally, public access is limited to the default path ("/"), and subpaths would require a valid OAuth Token supplied as a Bearer Authorization header. However, this solution employs a specific approach to allow access without OAuth Tokens for certain paths.

• Requests to the / path (e.g., https://script.google.com/macros/s/<your-id>/exec) are accessible without an OAuth Token. This path is treated as a special case and does not require additional authentication.

• Requests to subpaths (e.g., /my-sub-path) should be constructed as the first query parameter after the WebApp URL (https://script.google.com/macros/s/<your-id>/exec?/my-sub-path). These subpaths would require a valid OAuth Token supplied as a Bearer Authorization header.

Here's a reference table demonstrating how the paths would work:

Request Path	URL Format	Access Method
Special Subpath ("/")	https://script.google.com/macros/s/<your-id>/exec	Publicly accessible
Subpath ("/my-sub-path")	https://script.google.com/macros/s/<your-id>/exec?/my-sub-path	Requires OAuth Token
Another Subpath ("/another")	https://script.google.com/macros/s/<your-id>/exec?/another	Requires OAuth Token

This implementation ensures that paths following the / pattern can be accessed without OAuth Tokens, providing a workaround to the subpath constraint in Google Apps Script deployments. For paths not following this pattern, please remember to include the Bearer Authorization header with the OAuth Token when making requests.

Getting Started

// Import the library
const app = GasExpress;

// Set up the handler functions
doPost = app.doPost;
doGet = app.doGet;

// Add middleware to the GasExpress app
app.use(app.basicRouteLogger);
app.use(app.cacheMiddleware);
app.use(app.healthCheck);

// Define route handlers
app.get("/", function (request, response) {
  response({ message: "Hello, world!" });
});

app.get("/time", function (request, response) {
  const time = new Date();

  app.cache().add(request, { time });

  response({ time });
});

API Documentation

Class: GasExpress

The GasExpress class is the core component of GasExpress. It provides methods for defining routes, middleware functions, and caching responses.

GasExpress.get(path: string, handler: Function)

Adds a route handler for the GET method.

• path: A string representing the URL path to match for the GET request.
• handler: A function that will be executed when the route is matched. It receives the request and response objects as parameters.

GasExpress.post(path: string, handler: Function)

Adds a route handler for the POST method.

• path: A string representing the URL path to match for the POST request.
• handler: A function that will be executed when the route is matched. It receives the request and response objects as parameters.

GasExpress.use(middleware: Function)

Adds a middleware function to the middleware stack.

• middleware: A function that will be executed for every incoming request before the route handler. It receives the request, response, and next function as parameters. The next function should be called to pass control to the next middleware in the stack.

GasExpress.doPost(request: object): void

Handles an incoming POST request and executes the middleware and route handler.

• request: An object representing the incoming POST request with properties such as parameter and parameters.

GasExpress.doGet(request: object): void

Handles an incoming GET request and executes the middleware and route handler.

• request: An object representing the incoming GET request with properties such as parameter and parameters.

GasExpressCacheService

The GasExpressCacheService is a utility class used for caching and retrieving data in the User Cache.

GasExpress.cache()

Creates an instance of GasExpressCacheService for caching and retrieving data in the User Cache.

• Returns: An instance of GasExpressCacheService.

GasExpress.cacheMiddleware(request: GetRequest | PostRequest, response: ResponseHandler, next: NextHandler): void

Middleware function for caching responses based on the request in the User Cache. If a cached response exists for the request, it sends the cached response back to the client, otherwise, it passes control to the next middleware or route handler for processing.

• request: The incoming request object.
• response: The response handler function.
• next: The next middleware or route handler function.

GasExpress.healthCheck(request: GetRequest | PostRequest, response: ResponseHandler, next: NextHandler): void

Middleware function for handling a health check endpoint. If the request path is '/health', it immediately responds with a status of 'OK', otherwise, it passes control to the next middleware or route handler for processing.

• request: The incoming request object.
• response: The response handler function.
• next: The next middleware or route handler function.

Contributing

Contributions are welcome! If you have any ideas or find a bug, please open an issue or submit a pull request.

License

GasExpress is licensed under the MIT License - see the LICENSE file for details.