Winglang provides a solution for contributing to its Winglibs project. This is the way to go if you only need to wrap a particular cloud resource on one or more platforms. Just follow the guidelines. However, while developing the initial version of the Endor middleware framework, I had different needs.

First, the Endor library is in a very initial exploratory phase—far from a maturity level to be considered a contribution candidate for publishing in the public NPM Registry.

Second, it includes several supplementary and still immature tool libraries, such as Exceptions and Logging. These tools need to be published separately (see explanation below). Therefore, I needed a solution for managing multiple NPM Packages in one project.

Third, I wanted to explore how prospective Winglang customers will be able to manage their internal libraries.

For that goal, I decided to experiment with the AWS CodeArtifact service configured to play the role of my internal NPM Registry.

This publication is an experience report about the first phase, primarily focused on the developer’s experience with my Multi-Account, Multi-Platform, Multi-User (MAPU) environment, which I reported about here, here, and here. Specifically, I configured the AWS CodeArtifact Domain and Repository within my working account and postponed a more elaborate enterprise-grade system architecture to later stages. Let’s start with the overall solution overview.

Solution Overview

Here is a brief description of the solution:

1. Within my winglang account, I created an AWS CodeArtifact Domain tentatively named <organizationID>-platform.
2. Under this Domain, I created an AWS CodeArtifact Repository tentatively named winglang-artifacts.
3. This AWS CodeArtifact Repository is connected to the public npmjs repository, from which all third-party packages, including those from the official Winglibs, are downloaded.
4. The AWS CodeArtifact Repository contains two types of packages:
   1. Those that were developed and published locally.
   2. Those that were cloned from the external npmjs repository.
5. Locally developed packages belong to the @winglibs NPM Namespace. At the moment, this is a requirement determined by how the Winglang import system works.
6. The remote EC2 desktop instance is configured to use the AWS CodeArtifact Repository as its NPM Registry using a temporary session token valid for 12 hours.
7. As a developer, I communicate with my remote desktop using the VS Code Remote feature, described in the previous publication.

I found this arrangement suitable for a solo developer and researcher. A real organization, even of a middle size, will require some substantial adjustments — subject to further investigation.

Let’s now look at some technical implementation details.

Cloud Resources Allocation​

Using Cloud Formation templates is always my preferred option. In this case, I created two simple Cloud Formation templates. One for creating an AWS CodeArtifact Domain resource:

{
    "AWSTemplateFormatVersion": "2010-09-09",
    "Description": "Template to create a CodeArtifact Domain; to be a part of platform template",
    "Resources": {
        "ArtifactDomain": {
            "Type" : "AWS::CodeArtifact::Domain",
            "Properties" : {
                "DomainName" : "o-4e7dgfcrpx-platform"
            }
        }
    }
}

And another - for creating an AWS CodeArtifact Repository resource:

{
    "AWSTemplateFormatVersion": "2010-09-09",
    "Description": "Template to create a CodeArtifact repository; to be a part of account template",
    "Resources": {
        "ArtifactRespository": {
            "Type" : "AWS::CodeArtifact::Repository",
            "Properties" : {
                "Description" : "artifact repository for this <winglang> account",
                "DomainName" : "o-4e7dgfcrpx-platform",
                "RepositoryName": "winglang-artifacts", 
                "ExternalConnections" : [ "public:npmjs" ]
              }
          }
    }
}

These templates are mere placeholders for future, more serious, development.

The same could be achieved with Winglang, as follows:

https://gist.github.com/eladb/5e1ddd1bd90c53d90b2195d080397381

Many thanks to Elad Ben-Israel for bringing this option to my attention. Currently, the whole MAPU system is implemented in Python and CloudFormation. Re-implementing it completely in Winglang would be a fascinating case study.

Configuring npm with the login command​

I followed the official guidelines and created the following Bash script:

export CODEARTIFACT_AUTH_TOKEN=$(\
    aws codeartifact get-authorization-token \
    --domain o-4e7dgfcrpx-platform \
    --domain-owner 851725645964 \ 
    --query authorizationToken \
    --output text)
export REPOSITORY_ENDPOINT=$(\
    aws codeartifact get-repository-endpoint \
    --domain o-4e7dgfcrpx-platform \
    --domain-owner 851725645964 \
    --repository winglang-artifacts \
    --format npm \
    --query repositoryEndpoint \
    --output text)
export REGISTRY=$(echo "$REPOSITORY_ENDPOINT" | sed 's|https:||')
npm config set registry=$REPOSITORY_ENDPOINT
npm config set $REGISTRY:_authToken=$CODEARTIFACT_AUTH_TOKEN

Here is a brief description of the script’s logic:

1. Using the AWS CLI, retrieve an AWS CodeArtifact session token (valid for the next 12 hours).
2. Using the AWS CLI, the AWS CodeArtifact repository endpoint in a format compatible with NPM.
3. Use the NPM config command to set the endpoint.
4. Use the NPM config command to set up session authentication.

Placing this script in the [/etc/profile.d](https://www.linuxfromscratch.org/blfs/view/11.0/postlfs/profile.html) ensures that it will be automatically executed at every user login thus making the whole communication with AWS CodeArtifact instead of the official [npmjs](https://docs.npmjs.com/cli/v8/using-npm/registry) repository completely transparent for the end user.

Publishing Custom Libraries​

Implementing this operation while addressing my specific needs required a more sophisticated logic reflected in the following script:

#!/bin/bash
set -euo pipefail

# Function to clean up tarball and extracted package
cleanup() {
    rm *.tgz
    rm -fR package
}

# Function to calculate the checksum of a package tarball
calculate_checksum() {
    local tarball=$(ls *.tgz | head -n 1)
    tar -xzf "$tarball"
    cd package || exit 1
    local checksum=$(\
        tar \
        --exclude='$lib' \
        --sort=name \
        --mtime='UTC 1970-01-01' \
        --owner=0 \
        --group=0 \
        --numeric-owner -cf - . | sha256sum | awk '{print $1}')
    cd ..
    cleanup
    echo "$checksum"
}

get_version() {
    PACKAGE_VERSION=$(jq -r '.version' package.json)
}

publish() {
    echo "Publishing new version: $PACKAGE_VERSION"
    npm publish --access public --tag latest *.tgz
    cleanup
    exit 0
}

# Step 1: Read the package version from package.json
get_version
PACKAGE_NAME=$(jq -r '.name' package.json)

# Step 2: Check the latest version in the npm registry
LATEST_VERSION=$(npm show "$PACKAGE_NAME" version 2>/dev/null || echo "")

# Step 3: Prepare wing package
wing pack

# Step 4: If the versions are not equal, publish the new version
if [[ "$PACKAGE_VERSION" != "$LATEST_VERSION" ]]; then
    publish
else
    CURRENT_CHECKSUM=$(calculate_checksum)
    # Download the latest package tarball
    npm pack "$PACKAGE_NAME@$LATEST_VERSION" > /dev/null 2>&1
    LATEST_CHECKSUM=$(calculate_checksum)
    # Step 5: Compare the checksums
    if [[ "$CURRENT_CHECKSUM" == "$LATEST_CHECKSUM" ]]; then
        echo "No changes detected. Checksum matches the latest published version."
        exit 0
    else
        echo $CURRENT_CHECKSUM
        echo $LATEST_CHECKSUM
        echo "Checksums do not match. Bumping patch version..."
        npm version patch
        wing pack
        get_version
        publish
    fi
fi

Here is a brief explanation of what happens in this script:

1. Step 1: Using the [jq](https://jqlang.github.io/jq/) command, extract the package name and version from the package.json file.
2. Step 2: Using the [npm show](https://docs.npmjs.com/cli/v10/commands/npm-view) command, extract the package version number from the registry.
3. Step 3: Using the [wing pack](https://www.winglang.io/docs/libraries) command, prepare the package .tgz file.
4. Step 4: If version numbers differ, publish the new version using the [npm publish](https://docs.npmjs.com/cli/v10/commands/npm-publish) command.
5. Step 5: If the versions are equal, calculate the checksum for the current and most recently published package. If the checksum values are equal, do nothing. Otherwise, using the [npm version patch](https://docs.npmjs.com/cli/v10/commands/npm-version) command, automatically bump up the [patch](https://symver.org/) version number, rebuild the .tgz file, and publish the new version.

Reliable checksum validation was the most challenging part of developing this script. The wing pack command creates a special @lib folder within the resulting .tgz archive. This folder introduces some randomness and can be affected by several factors, including Winglang compiler upgrades. Additionally, the .tgz file checksum calculation is sensitive to the order and timestamps of individual files. As a result, comparing the results of direct checksum calculation for the current and published packages was not an option.

To overcome these limitations, new archives are created with the @lib folder excluded and file order and timestamps normalized. The assistance of the ChatGPT 4o tool proved instrumental, especially in addressing this challenge.

In the current implementation, I keep this script in my home directory and invoke it from a common [Build.mk](http://Build.mk) Makefile used for all libraries (this might change in the future):

.PHONY: all compile-deps build-ts prepare test publish

all: publish

update-deps:
    npm install && npm update

compile-ts: update-deps
ifneq ($(wildcard tsconfig.json),)
    @echo "tsconfig.json found, running tsc..."
    tsc
else
    @echo "tsconfig.json not found, skipping TypeScript compilation."
endif

test: compile-ts
    wing test -t sim ./test/*.test.w

publish: test
    ~/publish-npm.sh

Justification​

To explain why I chose this particular way of publishing logic, I need to explain my overall project structure, illustrated in the diagram below:

The top of the diagram above reflects the NMP packages involved and their dependencies are depicted at the top, while the bottom part reflects my project folder structure.

The endor package is the ultimate goal of this development activity: an exploratory middleware framework for the Winglang programming language. Its efficacy is validated by a separate todo.endor.w application. Initially, both modules were kept together. However, keeping pure application parts separate from the infrastructure became progressively challenging.

The endor package uses three auxiliary packages logging , exception, and datetimex. These three packages are potential candidates to be contributed to the Winglibs project. However, they are still under active experimentation and development and are kept within the same Github repository.

Additionally, the endor package depends on other packages published on the public [npmjs](https://docs.npmjs.com/cli/v8/using-npm/registry) registry. Some of these packages, such as dynamodb and jwt belong to the same @winglibs namespace, while others do not.

I face a mixed-case challenge: the system already has a modular structure, but all components are under intensive development, requiring instant propagation of changes. As a solo developer and researcher, I still do not need more sophisticated CI/CD solutions, but rather employ a master Makefile to pull everything together:

.PHONY: all \
              update_npm \
              update_wing \
              update_tsc \
              make_datetimex \
              make_exception \
              make_logging \
              make_endor

all:  update_wing make_endor

update_npm:
    sudo npm update -g npm

update_tsc: update_npm
    sudo npm update -g tsc

update_wing: update_tsc
    sudo npm update -g winglang

make_datetimex:
    $(MAKE) -C ./datetimex -f ../Build.mk

make_logging: make_datetimex
    $(MAKE) -C ./logging -f ../Build.mk

make_exception:
    $(MAKE) -C ./exception -f ../Build.mk

make_endor: make_exception make_logging
    $(MAKE) -C ./endor -f ../Build.mk

The todo.endor.w Makefile looks like this:

.PHONY: all update_wing install_endor test_local 

cloud ?= aws
target := target/main.tf$(cloud)

update_npm:
    sudo npm update -g npm

update_wing: update_npm
    sudo npm update -g winglang

install_endor:
    npm install && npm update

build_ts: 
    tsc

test_local: update_wing install_endor build_ts test_app

test_app:
    wing test -t sim ./test/*.w

test_remote:
    wing test -t tf-$(cloud) ./test/service.test.w

run_local:
    wing run -t sim ./dev.main.w

compile:
    wing compile ./main.w -t tf-$(cloud)

tf-init: compile
    ( \
        cd $(target) ;\
        terraform init \
    )

deploy: tf-init
    ( \
        cd $(target) ;\
        terraform apply -auto-approve \
    )

destroy:
    ( \
        cd $(target) ;\
        terraform destroy -auto-approve \
    )

This arrangement allows me to keep modules isolated, make changes in several places where appropriate, and perform fully automated build and verification without needing manual version updates within multiple package.json files.

Specifying cross-package dependencies is another point to pay attention to. Here is the endor package specification:

{
  "name": "@winglibs/endor",
  "description": "Wing middleware framework library",
  "repository": {
    "type": "git",
    "url": "https://github.com/asterkin/endor.w.git",
    "directory": "endor"
  },
  "version": "0.0.19",
  "author": {
    "email": "asher.sterkin@gmail.com",
    "name": "Asher Sterkin"
  },
  "license": "MIT",
  "peerDependencies": {
    "@authenio/samlify-node-xmllint": "2.x.x",
    "@winglibs/dynamodb": "0.x.x",
    "@winglibs/jwt": "0.x.x",
    "qs": "6.x.x",
    "samlify": "2.x.x",
    "ws": "8.x.x",
    "inflection": "3.x.x",
    "@winglibs/exception": "0.x.x",
    "@winglibs/logging": "0.x.x"
  }
}

Notice that, unlike traditional formats, all dependencies are specified using the x placeholder without the leading ^ symbol. This is because, with the ^ prefix included, the most up-to-date versions are brought in only for the final todo.endor.w application, whereas I needed them to be used in the dependent modules' unit tests. Using the x placeholder instead does the job.

In summary, while not final, the described solution provides good enough treatment for all essential requirements at the current stage of the system evolution. As the system grows, adequate adjustments will be implemented and reported. Stay tuned.

Acknowledgments

Throughout the preparation of this publication, I utilized several key tools to enhance the draft and ensure its quality.

The initial draft was crafted with the organizational capabilities of Notion's free subscription, facilitating the structuring and development of ideas.

For grammar and spelling review, the free version of Grammarly proved useful for identifying and correcting basic errors, ensuring the readability of the text.

The enhancement of stylistic expression and the narrative coherence checks were performed using the paid version of ChatGPT 4o. The ChatGPT 4o tool was also used for developing the package publishing script and creation of NMP elements icons.

While these advanced tools and resources significantly contributed to the preparation process, the concepts, solutions, and final decisions presented in this article are entirely my own, for which I bear full responsibility.

Winglang's unique capability to uniformly handle both preflight (cloud resource configuration) and inflight (cloud events processing) logic opens up meta-programming possibilities akin to Lisp macros. This allows for the dynamic adjustment of service configurations to various deployment targets—such as DEV, TEST, STAGE, and PROD—at the build stage. By doing so, it optimizes cost, security, and performance without compromising the integrity of the core service logic, which remains largely insulated from middleware framework details. This level of flexibility is unmatched by more traditional cloud middleware libraries, such as PowerTools for AWS Lambda, which I explored in the first part of this series.

In this part, I will explore how a middleware framework can leverage the Template Method Design Pattern. This design pattern has proven instrumental in defining the common elements of the REST API Create/Retrieve/Update/Delete (CRUD) request handling flow, while still allowing enough flexibility to accommodate the specifics of each request.

Specifically, the application of the Template Method Design Pattern to define a common request-handling workflow has demonstrated the following benefits:

• Unlike Decorator, it organically presents post-processing steps of request handling in their natural sequence.
• It facilitates the reuse of a common request-handling definition across all functions related to a resource, service, or even across all services developed by the same team or organization.
• It enables the specification of multiple configurations optimized for various deployment targets (DEV, TEST, STAGE, PROD), addressing variability at the build stage to eliminate unnecessary overhead and security risks.

Nevertheless, this approach has limitations. A high number of deployment targets, services, resources, and function permutations may necessitate maintaining a large number of templates—a common challenge in any Engineering Platform based on blueprints.

Exploring whether these limitations can be surmounted using Winglang's unique capabilities will be the focus of future research.

Common Service Middleware

As clarified in the previous publication,

Common middleware services augment distribution middleware by defining higher-level domain-independent reusable services that allow application developers to concentrate on programming business logic, without the need to write the “plumbing” code required to develop distributed applications via lower-level middleware directly.

In our pursuit, we specifically aim to define common service configurations that are adaptable to various development targets. Such configurations are not only reusable across multiple services and resources within the same team or organization but are also distinct enough not to be overgeneralized in the form of a framework but rather to merit integration into a tailored Engineering Platform. This balance ensures that while the configurations maintain a high level of generality, they remain sufficiently detailed to support the unique needs of different projects within the organization.

Here is an example of how common service configurations can be implemented using Winglang. Typically, this or a similar code snippet will be a part of a larger solution integrated into an organization's or team's engineering platform:

bring endor;
bring cloud;
bring logging;

//Could be a part of an organization or team engineering platform
pub class ServiceFactory impl endor.IRestApiHandlerTemplate {
    _tools: endor.ApiTools;
    _mode: endor.Mode;
    pub logger: logging.Logger;
    pub api: cloud.Api;

    _getLoggingLevel(mode: endor.Mode): logging.Level {
        if mode == endor.Mode.PROD {
            return logging.Level.INFO;
        } elif mode == endor.Mode.DEV {
            return logging.Level.TRACE;
        } else {
            return logging.Level.DEBUG;
        }
    }

    _getToolsOptions(
        mode: endor.Mode,
        logger: logging.Logger
    ): endor.ApiToolsOptions {
        if mode == endor.Mode.DEV {
            return endor.ApiToolsOptions{
                logger: logger,
                statusMessage: Map<str>{} // leave original error messages intact
            };
        }
        return endor.ApiToolsOptions{
            logger: logger
        }; // use defaults
    }

    new(serviceName: str, mode: endor.Mode) {
        this._mode = mode;
        this.logger = new logging.Logger(
            this._getLoggingLevel(mode),
            serviceName);
        this._tools = new endor.ApiTools(
            this._getToolsOptions(mode,
            this.logger));
        this.api = new cloud.Api();
    }

    _getProdApiBuilder(
        resource: endor.ApiResource,
        responseFormats: Array<str>,
        getHomePage: (inflight (Json, str): str)?
    ): endor.RestApiBuilder {
        let tokenFactory = new endor.FixedSecretTokenFiltersFactory();
        let cookieFactory = new endor.CookieAuthFiltersFactory(tokenFactory);
        let apiBuilder = new endor.RestApiBuilder(
            this.api,
            resource,
            this,
            cookieFactory,
            responseFormats);
        if getHomePage != nil {
            apiBuilder.samlLogin(cookieFactory, getHomePage!);
        }
        return apiBuilder;
    }
    _getDevApiBuilder(
        resource: endor.ApiResource,
        responseFormats: Array<str>,
        getHomePage: (inflight (Json, str): str)?
    ): endor.RestApiBuilder {
        let session = Json {
            userID: "test-user",
            fullName: "Test User"
        };
        let stubAuth = new endor.ApiStubAuthFactory(session);
        let apiBuilder = new endor.RestApiBuilder(
            this.api,
            resource,
            this,
            stubAuth,
            responseFormats);
        if getHomePage != nil {
            apiBuilder.stubLogin(session, getHomePage!);
        }
        return apiBuilder;
    }
    _getDefaultApiBuilder(
        resource: endor.ApiResource,
        responseFormats: Array<str>,
        password: str
    ): endor.RestApiBuilder {
        let basicAuth = new endor.ApiBasicAuthFactory(password);
        let apiBuilder = new endor.RestApiBuilder(
            this.api,
            resource,
            this,
            basicAuth,
            responseFormats);
        return apiBuilder;
    }
    pub getApiBuilder(
        resource: endor.ApiResource,
        responseFormats: Array<str>,
        getHomePage: (inflight (Json, str): str)?,
        password: str?
    ): endor.RestApiBuilder {
        if this._mode == endor.Mode.PROD {
            return this._getProdApiBuilder(
                resource,
                responseFormats,
                getHomePage);
        } elif this._mode == endor.Mode.DEV {
            return this._getDevApiBuilder(
                resource,
                responseFormats,
                getHomePage);
        } else {
            return this._getDefaultApiBuilder(
                resource,
                responseFormats,
                password!);
        }
    }

    pub makeRequestHandler(
        functionName: str,
        proc: inflight (cloud.ApiRequest): cloud.ApiResponse
    ): inflight(cloud.ApiRequest): cloud.ApiResponse {
        let handler = inflight (request: cloud.ApiRequest): cloud.ApiResponse => {
            let var response = cloud.ApiResponse{};
            try {
                this._tools.logRequest(functionName, request);
                response = proc(request);
            } catch err {
                response = this._tools.errorResponse(err);
            }
            this._tools.logResponse(functionName, response);
            response = this._tools.responseMessage(response);
            return response;
        };
        return handler;
    }

}

This example is quite detailed, so we will break it down section by section to fully understand its structure and functionality.

This module, by convention named middleware.w, features a Winglang preflight class called ServiceFactory. This class encapsulates the following public resources and methods, which are crucial for the middleware's operation:

• api: [cloud.Api](https://www.winglang.io/docs/standard-library/cloud/api): resource from the Winglang Standard Library
• logger: logging.Logger: resource, extending the Winglang libraries, which was discussed previously in terms of its utility and possible implementation implementation here
• makeRequestHandler(): Factory Method that applies the Template Method Design Pattern tailored to each request handler
• getApiBuilder(): another Factory Method this time applying the Builder Design Pattern to configure specific resource API calls

makeRequestHandler() Factory Method​

    pub makeRequestHandler(
        functionName: str,
        proc: inflight (cloud.ApiRequest): cloud.ApiResponse
    ): inflight(cloud.ApiRequest): cloud.ApiResponse {
        let handler = inflight (request: cloud.ApiRequest): cloud.ApiResponse => {
            let var response = cloud.ApiResponse{};
            try {
                this._tools.logRequest(functionName, request);
                response = proc(request);
            } catch err {
                response = this._tools.errorResponse(err);
            }
            this._tools.logResponse(functionName, response);
            response = this._tools.responseMessage(response);
            return response;
        };
        return handler;
    }

This Factory Method plays a central role in implementing the Common Service Middleware. It is a Winglang preflight method that obtains two parameters:

• functionName: The name of the function handling the API request, used for logging purposes.
• proc: a Winglang inflight function that transforms cloud.ApiRequest into a cloud.ApiResponse

Internally, it defines a Winglang inflight function, called handler that encapsulates a typical API request processing workflow:

1. Logging the Request: Initially logs the incoming cloud.ApiRequest.
2. Processing the Request: Executes the proc function to obtain a cloud.ApiResponse.
3. Error Handling: In the case of an error, it transforms the error into an appropriate cloud.ApiResponse.
4. Response Logging: Logs the outgoing cloud.ApiResponse.
5. Error Message Management: Modifies the error message in the response based on the configuration to prevent leakage of sensitive information to potential attackers.

Operations for logging and error handling are managed using the auxiliary endor.ApiTools class, which we will explore in further detail later.

getApiBuilder() Factory Method​

The getApiBuilder() method, another key component implemented as a Factory Method, dynamically creates a properly configured API Builder for a specific resource, depending on the deployment mode:

pub getApiBuilder(
        resource: endor.ApiResource,
        responseFormats: Array<str>,
        getHomePage: (inflight (Json, str): str)?,
        password: str?
    ): endor.RestApiBuilder {
        if this._mode == endor.Mode.PROD {
            return this._getProdApiBuilder(
                resource,
                responseFormats,
                getHomePage);
        } elif this._mode == endor.Mode.DEV {
            return this._getDevApiBuilder(
                resource,
                responseFormats,
                getHomePage);
        } else {
            return this._getDefaultApiBuilder(
                resource,
                responseFormats,
                password!);
        }
    }

This Winglang preflight method accepts four parameters:

• resource: A Winglang Struct defining the API resource, including its names and HTTP paths for singular and plural operations.
• responseFormats: A Winglang Array specifying supported response formats, such as application/json, text/html, or text/plain.
• getHomePage: An optional Winglang inflight function to fetch the home page content using session data and the required format.
• password: An optional string for temporary use in HTTP Basic Authentication.

Based on the _mode field, the method directs the construction of the appropriate builder:

• It calls _getProdApiBuilder for the PROD mode.
• It invokes _getDevApiBuilder for the DEV mode.
• It defaults to _getDefaultApiBuilder in other cases.

The main variability point that distinguishes these three options is the authentication strategy applied to each API request. Let's examine the specifics of each builder's implementation.

_getProdApiBuilder() Factory Method​

_getProdApiBuilder(
        resource: endor.ApiResource,
        responseFormats: Array<str>,
        getHomePage: (inflight (Json, str): str)?
    ): endor.RestApiBuilder {
        let tokenFactory = new endor.FixedSecretTokenFiltersFactory();
        let cookieFactory = new endor.CookieAuthFiltersFactory(tokenFactory);
        let apiBuilder = new endor.RestApiBuilder(
            this.api,
            resource,
            this,
            cookieFactory,
            responseFormats);
        if getHomePage != nil {
            apiBuilder.samlLogin(cookieFactory, getHomePage!);
        }
        return apiBuilder;
    }

For production environments, the security of API requests is paramount. This method implements stringent authentication protocols using JSON Web Tokens (JWT) embedded within Cookie HTTP Headers. The JWTs are signed with a fixed random key, a cost-effective measure that maintains robust security for services at this level.

This Winglang preflight method sets up the described security configuration. Additionally, if the getHomePage parameter is not nil, the method configures an extra HTTP request handler for SAML-based authentication, offering another layer of security and user verification (further details on this process can be found here).

_getDevApiBuilder() Factory Method​

_getDevApiBuilder(
        resource: endor.ApiResource,
        responseFormats: Array<str>,
        getHomePage: (inflight (Json, str): str)?
    ): endor.RestApiBuilder {
        let session = Json {
            userID: "test-user",
            fullName: "Test User"
        };
        let stubAuth = new endor.ApiStubAuthFactory(session);
        let apiBuilder = new endor.RestApiBuilder(
            this.api,
            resource,
            this,
            stubAuth,
            responseFormats);
        if getHomePage != nil {
            apiBuilder.stubLogin(session, getHomePage!);
        }
        return apiBuilder;
    }

For development purposes, especially when using the Winglang Simulator in interactive mode, security requirements can be relaxed. In this mode, authentic security is not required, allowing developers to focus on functionality and flow without the overhead of complex security protocols.

This Winglang preflight method implements such a setup. It uses a stub authentication system based on predefined user session data. Furthermore, if the getHomePage parameter is supplied and not nil, the method adds an HTTP request handler that simulates the login process, maintaining the integrity of the user experience even in a simulated environment.

_getDefaultApiBuilder() Factory Method​

_getDefaultApiBuilder(
        resource: endor.ApiResource,
        responseFormats: Array<str>,
        password: str
    ): endor.RestApiBuilder {
        let basicAuth = new endor.ApiBasicAuthFactory(password);
        let apiBuilder = new endor.RestApiBuilder(
            this.api,
            resource,
            this,
            basicAuth,
            responseFormats);
        return apiBuilder;
    }

For test and stage modes, where end-to-end testing is routinely performed, a balance between security, cost-efficiency, and performance is essential. Unlike local simulations that utilize stub authentication similar to the development environment, end-to-end tests in real cloud platforms like AWS require more robust security.

This Winglang preflight method achieves this by implementing HTTP Basic Authentication. It utilizes a dynamically generated password to ensure security while maintaining cost efficiency. The use of HTTP Basic Authentication, where credentials are passed directly in the header, eliminates the need for separate login request handling, streamlining the testing process.

ServiceFactory Object Initialization​

Proper initialization of the ServiceFactory object is crucial for the functionality of its public methods and fields. Below is a detailed look into its initialization process:

bring endor;
bring cloud;
bring logging;

//Could be a part of organization or team engineering platform
pub class ServiceFactory impl endor.IRestApiHandlerTemplate {
    _tools: endor.ApiTools;
    _mode: endor.Mode;
    pub logger: logging.Logger;
    pub api: cloud.Api;

    _getLoggingLevel(mode: endor.Mode): logging.Level {
        if mode == endor.Mode.PROD {
            return logging.Level.INFO;
        } elif mode == endor.Mode.DEV {
            return logging.Level.TRACE;
        } else {
            return logging.Level.DEBUG;
        }
    }

    _getToolsOptions(
        mode: endor.Mode,
        logger: logging.Logger
    ): endor.ApiToolsOptions {
        if mode == endor.Mode.DEV {
            return endor.ApiToolsOptions{
                logger: logger,
                statusMessage: Map<str>{} // leave original error messages intact
            };
        }
        return endor.ApiToolsOptions{
            logger: logger
        }; // use defaults
    }

    new(serviceName: str, mode: endor.Mode) {
        this._mode = mode;
        this.logger = new logging.Logger(
            this._getLoggingLevel(mode),
            serviceName);
        this._tools = new endor.ApiTools(
            this._getToolsOptions(mode,
            this.logger));
        this.api = new cloud.Api();
    }

The new() constructor method is designed to take two parameters:

• serviceName: Utilized in all log messages to identify service-specific operations.
• mode: Determines the appropriate configuration settings for different operational environments.

The initialization sequence performs the following steps:

1. Mode Configuration: Stores the mode to dictate the behavior of the getApiBuilder() method.
2. Logger Initialization: Creates a Logger object with a logging level based on mode:
   • INFO for PROD for streamlined logging.
   • TRACE for DEV to enable detailed debugging.
   • DEBUG for other environments to balance detail and performance.
3. ApiTools Configuration: Establishes an endor.ApiTools object with settings influenced by mode:
   • Retains original error messages in DEV mode to aid in debugging.
   • Replaces error messages with standard HTTP response text in other modes to safeguard against potential security risks.

This ServiceFactory class, by implementing the endor.IRestApiHandlerTemplate interface, seamlessly integrates with the endor.RestApiBuilder. This allows the latter to utilize the makeRequestHandler() method of ServiceFactory, thus ensuring consistent handling of all API requests.

TodoService

The common middleware service configuration described previously hides a substantial portion of the system infrastructure complexity, allowing specific service configurations to be defined with ease and precision. A practical implementation of this approach can be seen in the TodoService, first introduced in the previous publication:

bring endor;
bring cloud;
bring logging;
bring "./core" as core;
bring "./adapters" as adapters;
bring "./middleware.w" as middleware;

pub class TodoService {
    _api: cloud.Api;

    //TODO: true content negotiation; unit test?; move to adapters??
    _getResponseFormatters(
            mode: endor.Mode,
            resource: endor.ApiResource
        ): Map<core.ITodoFormatter> {
        if mode == endor.Mode.TEST {
            return Map<core.ITodoFormatter> {
                "application/json" => new adapters.TodoJsonFormatter()
            };
        }
        return Map<core.ITodoFormatter> {
            "text/html" => new adapters.TodoHtmlFormatter(resource.htmlPath),
            "text/plain" => new adapters.TodoTextFormatter(),
        };
    }

    new(mode: endor.Mode, password: str?) {
        let serviceName = "Todo Service";
        let factory = new middleware.ServiceFactory(serviceName, mode);
        let resource = new endor.ApiResource("Task");
        let responseFormatters = this._getResponseFormatters(mode, resource);
        let repository = new adapters.TaskTableRepository(factory.logger);
        let handler = new core.TodoHandler(
            repository,
            responseFormatters,
            factory.logger
        );
        let apiBuilder = factory.getApiBuilder(
            mode,
            resource,
            responseFormatters.keys(),
            handler.getHomePage(),
            password
        );

        apiBuilder.retrieveResources(handler.getAllTasks());
        apiBuilder.createResource(handler.createTask());
        apiBuilder.replaceResource(handler.replaceTask());
        apiBuilder.deleteResource(handler.deleteTask());
        this._api = factory.api;
    }

    pub getUrl(): str {
        return this._api.url;
    }
}

The TodoService class serves as a Winglang preflight entity that orchestrates the integration of the service core, its adapters, and middleware. It includes a public getUrl() method for testing purposes.

Service Initialization​

The new() constructor method takes two parameters:

• mode: Determines the output format selection and middleware configuration.
• password: An optional string for HTTP Basic Authentication in scenarios requiring secure access.

The service is initialized through the following steps:

1. Middleware Configuration: Initializes a ServiceFactory with serviceName and mode.
2. Resource Descriptor: Sets up a Task resource descriptor that translates to the /tasks HTTP path.
3. Response Formatter Configuration: Depending on the mode, it configures response formatters:
   • application/json for TEST mode.
   • text/html and text/plain for PROD and DEV modes.
4. Repository Creation: Establishes a Tasks repository using a DynamoDB backend.
5. Handler Setup: Configures a core.TodoHandler with necessary dependencies, including a logger from ServiceFactory.
6. API Builder Setup: Uses ServiceFactory.getApiBuilder() to link TodoHandler methods to respective REST API endpoints.
7. REST API Wiring: Connects TodoHandler methods to the corresponding REST API calls.
8. API Object Storage: Retains the cloud.Api object to handle URL retrieval via getUrl().

Configurations​

This TodoService can be instantiated with different target modes and optionally a random password, resulting in three primary configurations for various environments:

1. Production: let _service = new service.TodoService(endor.Mode.PROD);
2. Development: let _service = new service.TodoService(endor.Mode.DEV);
3. Testing: let _service = new service.TodoService(endor.Mode.TEST, _password);

Design Diagram​

While detailed code snippets and textual descriptions provide precise insight into design decisions, they often fall short of conveying a holistic view. For a broader perspective, visual representations are invaluable, especially when dealing with concepts as abstract as higher-order programming utilized by Winglang's preflight/inflight mechanisms. This section aims to bridge this understanding gap through graphical illustrations.

To visualize core system components and their relationships a UML Class diagram is a suitable tool:

In this diagram, solid arrows indicate permanent references, dashed arrows depict temporal interactions, and diamond-ended lines show component aggregations. This static representation helps delineate how components are interconnected during the preflight phase.

However, to visualize what happens dynamically at the inflight stage, a more specialized notation is necessary. Traditional UML communication and sequence diagrams were found inadequate, prompting the creation of a custom notation specifically designed for this purpose.

Illustrated below is the createTask with HTTP Basic Authentication scenario:

In this diagram:

• Circles with transparent backgrounds represent individual functional steps.
• Circles with grey backgrounds denote template method plug-in function sockets.
• Rounded rectangles indicate top-level functions.
• Dashed arrows symbolize standard function calls, while solid arrows indicate indirect function calls via function references.

Interpretation of the Diagram​

1. An incoming HTTP POST request is received by the cloud resource (e.g., AWS API Gateway), which uses the Winglang cloud.Api to convert it into a cloud.ApiRequest and invokes the appropriate inflight function, typically specified within the RestApiHandlerTemplate (here, implemented by ServiceFactory).
2. The api request handling process begins within a try block, where the logRequest function from ApiTools logs the request, and the plugged-in function (createResource from RestApiBuilder) processes the request. Upon error, errorResponse from ApiTools converts exceptions into cloud.ApiResponse. Regardless of the outcome, logResponse and responseMessage from ApiTools are invoked to finalize the processing.
3. The createResource function within RestApiBuilder initiates authentication via a plugged-in auth function (provided by BasicAuthFactory), which extracts user data and passes control to createResource of RestApiFactory.
4. Finally, createResource in RestApiFactory parses HTTP headers and body data and calls the createTask function provided by TodoHandler, which handles the core business logic.

This dynamic interaction is indeed complex, highlighting the intricate and interconnected nature of the system. The proposed middleware design aims to shield users from this complexity in daily operations. However, when issues arise, creating a precise graphical representation of the underlying system dynamics becomes essential. Future research will likely focus on developing tools to maintain cognitive control over such complex systems, ensuring that developers can effectively manage and troubleshoot without being overwhelmed.

Todo Service Core​

The architecture adopted allows the service core to remain independent of any middleware framework, focusing on core functionality without being tangled in middleware specifics. An example of this is the core.TodoHandler class:

bring logging;
bring "./task.w" as task;
bring "./parser.w" as parser;
bring "./formatter.w" as formatter;

// Experimental implementation of
// "Preflight Object Oriented, Inflight Functional"
// Design Pattern
pub class TodoHandler {
    _tasks: task.ITaskDataRepository;
    _parser: parser.TodoParser;
    _formatter: formatter.TodoFormattingRouter;
    _logger: logging.Logger;

    new(
        tasks_: task.ITaskDataRepository,
        formatters: Map<formatter.ITodoFormatter>,
        logger: logging.Logger
    ) {
        this._tasks = tasks_;
        this._parser = new parser.TodoParser();
        this._formatter = new formatter.TodoFormattingRouter(formatters);
        this._logger = logger;
    }

    pub getHomePage(): inflight (Json, str): str {
        let handler = inflight (user: Json, outFormat: str): str => {
            let userData = this._parser.parseUserData(user);

            return this._formatter.formatHomePage(outFormat, userData);
        };
        return handler;
    }

    pub getAllTasks(): inflight (Json, Map<str>, str): str {
        let handler = inflight (
            user: Json,
            query: Map<str>,
            outFormat: str
        ): str => {
            let userData = this._parser.parseUserData(user);
            //TBD: should it get userData instead?
            let tasks = this._tasks.getTasks(userData.userID);

            return this._formatter.formatTasks(outFormat, tasks);
        };
        return handler;
    }

    pub createTask(): inflight (Json, Json, str): str {
        let handler = inflight (
            user: Json,
            taskAttributes: Json,
            outFormat: str
        ): str => {
            let taskData = this._parser.parsePartialTaskData(
                user,
                taskAttributes);
            this._tasks.addTask(taskData);
            //TBD: cloud events?
            this._logger.info(
                "createTask",
                Json{userID: taskData.userID, taskID:taskData.taskID});

            return this._formatter.formatTasks(outFormat, [taskData]);
        };
        return handler;
    }

    pub replaceTask(): inflight (Json, str, Json, str): str {
        let handler = inflight (
            user: Json,
            id: str,
            taskAttributes: Json,
            outFormat: str
        ): str => {
            let taskData = this._parser.parseFullTaskData(
                user,
                id,
                taskAttributes);
            this._tasks.replaceTask(taskData);
            //TBD: cloud events?
            this._logger.info(
                "replaceTask",
                Json{userID: taskData.userID, taskID:taskData.taskID});

            return this._formatter.formatTasks(outFormat, [taskData]);
        };
        return handler;
    }

    pub deleteTask(): inflight (Json, str): str {
        let handler = inflight (user: Json, id: str): str => {
            let userData = this._parser.parseUserData(user);
            let taskID = num.fromStr(id);
            //TBD: taskKey? userData?
            this._tasks.deleteTask(userData.userID, taskID);
            //TBD: cloud events?
            this._logger.info(
                "deleteTask",
                Json{userID: userData.userID, taskID:taskID});

            return ""; //TBD: formatter?
        };
        return handler;
    }
}

The core.TodoHandler is designed as a Winglang preflight class that encapsulates key functionalities for Todo Service operations. Each method in this class exemplifies a Factory Method, returning specialized inflight functions that handle specific aspects of Todo management.

The only implicit coupling between the core of the Todo Service and its middleware lies in the parameters passed to each function. This level of coupling, referred to as Knowledge Sharing, is a trade-off typically considered acceptable in such architectural designs, facilitating seamless integration while maintaining a clear separation of concerns.

Interestingly enough, introducing Generics support in Winglang could potentially increase rather than decrease system coupling. With Generics, the coordination between the core and middleware layers would extend beyond just the order and types of parameters. It would also necessitate sharing the names of functions and their parameters, thereby tightening the interdependence within the system.

The following UML class diagram summarizes the Todo Service logic design in visual form:

A detailed description of this design is presented in a previous publication.

Endor Middleware Framework

The ServiceFactory class, detailed earlier, relies on the Endor middleware framework—an experimental library designed to push the boundaries of what is possible with Winglang, a new cloud-oriented programming language.

The name "Endor", derived from Quenya—a functional language created by J.R.R. Tolkien for the Elves in his Middle-earth fiction—translates to "Middle-earth." This nomenclature not only signifies 'middle' but also metaphorically represents our exploration into Winglang's unleashed yet potential, positioning it as a pioneering language at the crossroads of established practices and innovative paradigms.

In its current iteration, the Endor middleware framework encapsulates an initial set of functionalities for HTTP request handling, including various authentication methods. While a comprehensive review of the entire framework is outside the scope of this publication, we will briefly explore the Endor.ApiBuilder class implementation, which plays a crucial role in integrating application-specific handlers into a common request processing infrastructure:

bring cloud;
bring "./apiStubAuth.w" as apiStubAuth;
bring "./apiResource.w" as apiResource;
bring "./apiAuthFactory.w" as authFactory;
bring "./restApiFactory.w" as restApiFactory;
bring "./cookieAuthFilters.w" as cookieFilters;

pub interface IRestApiHandlerTemplate {
    makeRequestHandler(
        functionName: str,
        proc: inflight (cloud.ApiRequest): cloud.ApiResponse
    ): inflight (cloud.ApiRequest): cloud.ApiResponse;
}

pub class RestApiBuilder {
    _resource: apiResource.ApiResource;
    _template: IRestApiHandlerTemplate;
    _factory: restApiFactory.RestApiFactory;
    _auth: (inflight (cloud.ApiRequest): Json);
    _api: cloud.Api;

    new(
        api: cloud.Api,
        resource: apiResource.ApiResource,
        template: IRestApiHandlerTemplate,
        authFactory: authFactory.IApiAuthFactory,
        responseFormats: Array<str>
    ) {
        this._resource = resource;
        this._template = template;
        this._factory = new restApiFactory.RestApiFactory(responseFormats);
        this._auth = authFactory.getAuth();
        this._api = api;
    }

    _makeAuthRequestHandler(
        functionName: str,
        proc: inflight (Json, cloud.ApiRequest): cloud.ApiResponse
    ): inflight(cloud.ApiRequest): cloud.ApiResponse {
        let handler = inflight(request: cloud.ApiRequest): cloud.ApiResponse => {
            let userData = this._auth(request);
            return proc(userData, request);
        };
        return this._template.makeRequestHandler(functionName, handler);
    }

    pub samlLogin(
        cookieFactory: cookieFilters.CookieAuthFiltersFactory,
        getHomePage: inflight (Json, str): str
    ): void {
        this._api.post(
            "/sp/acs",
            this._template.makeRequestHandler(
                "login",
                this._factory.samlLogin(cookieFactory, getHomePage)
            )
        );
    }

    pub stubLogin(
        session: Json,
        getHomePage: inflight (Json, str): str
    ): void {
        this._api.get(
            "/",
            this._template.makeRequestHandler(
                "login",
                this._factory.stubLogin(session, getHomePage)
            )
        );
    }

    pub retrieveResources(
        handler: inflight (Json, Map<str>, str): str
    ): void {
        this._api.get(
            this._resource.path,
            this._makeAuthRequestHandler(
                "get{this._resource.plural}",
                this._factory.retrieveResources(
                    handler
                )
            )
        );
    }

    pub createResource(
        handler: inflight (Json, Json, str): str
    ): void {
        this._api.post(
            this._resource.path,
            this._makeAuthRequestHandler(
                "create{this._resource.singular}",
                this._factory.createResource(
                    handler
                )
            )
        );
    }

    pub replaceResource(
        handler: inflight (Json, str, Json, str): str
    ): void {
        this._api.put(
            this._resource.idPath,
            this._makeAuthRequestHandler(
                "replace{this._resource.singular}",
                this._factory.replaceResource(
                    handler
                )
            )
        );
    }

    pub deleteResource(
        handler: inflight (Json, str): str
    ): void {
        this._api.delete(
            this._resource.idPath,
            this._makeAuthRequestHandler(
                "delete{this._resource.singular}",
                this._factory.deleteResource(
                    handler
                )
            )
        );
    }

    //TODO: other operations: partial update (patch), has (head), delete all, update all
}

The RestApiBuilder class is designed to wrap application-specific handlers, such as createTask(), within a standardized cloud API request-response conversion process, seamlessly incorporating specified authentication methods. The conversion from cloud.ApiRequest to cloud.ApiResponse is further handled by the endor.RestApiFactory, whose details are not covered in this publication.

The endor.ApiTools class, another significant component of the framework, provides a suite of middleware operations:

bring cloud;
bring logging;
bring exception;

pub struct ApiToolsOptions {
    logger: logging.Logger;
    logLevel: logging.Level?;
    statusMessage: Map<str>?;
    statusLogging: Map<logging.Level>?;
}

//TODO: unit test
pub class ApiTools {
    _logger: logging.Logger;
    _logLevel: logging.Level;
    _errorStatus: Map<num>;
    _statusMessage: Map<str>;
    _statusLogging: Map<logging.Level>;

    new(
        options: ApiToolsOptions
    ) {
        this._logger = options.logger;
        this._logLevel = options.logLevel ?? logging.Level.DEBUG;
        this._errorStatus = Map<num>{
            "ValueError" => 400,
            "AuthenticationError" => 401,
            "AuthorizationError" => 403,
            "KeyError" => 404,
            "InternalError" => 500,
            "NotImplementedError" => 501
        };
        this._statusMessage = options.statusMessage ?? Map<str> {
            "400" => "Bad Request",
            "401" => "Unauthorized",
            "403" => "Forbidden",
            "404" => "Not Found",
            "500" => "Internal Server Error",
            "501" => "Not Implemented"
        };
        this._statusLogging = options.statusLogging ?? Map<logging.Level> {
            "200" => logging.Level.DEBUG,
            "400" => logging.Level.WARNING,
            "401" => logging.Level.WARNING,
            "403" => logging.Level.WARNING,
            "404" => logging.Level.WARNING,
            "500" => logging.Level.ERROR,
            "501" => logging.Level.ERROR,
        };
    }
    pub inflight logRequest(functionName: str, request: cloud.ApiRequest): void {
        this._logger.log(
            this._logLevel,
            functionName,
            Json{
                request: Json.parse(Json.stringify(request))
            }
        );
    }
    pub inflight logResponse(functionName: str, response: cloud.ApiResponse): void {
        if let logLevel = this._statusLogging.tryGet("{response.status!}") {
            this._logger.log(
                logLevel,
                functionName,
                Json{
                    response: Json.parse(Json.stringify(response))
                }
            );
        }
    }
    pub inflight errorResponse(err: str): cloud.ApiResponse {
        if let error = exception.tryParse(err) {
            if let status = this._errorStatus.tryGet(error.tag) {
                return cloud.ApiResponse {
                    status: status,
                    headers: {
                        "Content-Type" => "text/plain"
                    },
                    body: error.message
                };
            }
        }
        return cloud.ApiResponse {
            status: 500,
            headers: {
                "Content-Type" => "text/plain"
            },
            body: err
        };
    }
    pub inflight responseMessage(response: cloud.ApiResponse): cloud.ApiResponse {
        if let message = this._statusMessage.tryGet("{response.status!}") {
            return cloud.ApiResponse{
                status: response.status,
                headers: response.headers,
                body: message
            };
        }
        return response;
    }
}