Foxx Builder v2.4.0 - GitHub Actions CI/CD & Enhanced Documentation

🚀 Foxx Builder v2.4.0

Major Features & Improvements

🔄 Complete CI/CD Migration

• Migrated from Circle CI to GitHub Actions - Native GitHub integration with better security and performance
• Automated testing pipeline - Full API test suite runs on every push and PR
• Production deployment automation - Tag-based releases with automatic deployment
• Enhanced security scanning - Built-in code quality checks and dependency audits

📚 Comprehensive Documentation Overhaul

• Completely rewritten wiki pages with compelling, benefit-focused content
• 100% accuracy verification - All documented features confirmed to exist in codebase
• Enhanced developer experience - Clear examples, practical workflows, and real-world guidance
• Updated project structure documentation - Accurate folder organization and development patterns

🛠 Enhanced Development Experience

• Improved Taskfile automation - Streamlined local development workflow
• Better error handling - More resilient service setup and deployment
• Enhanced test organization - Moved API tests to tests/hurl/ for better structure
• Docker networking improvements - More reliable local development setup

🔧 Technical Improvements

Context Utilities & Framework

• Enhanced database operations with transaction support
• Vector search capabilities for AI-powered features
• Improved authentication system with middleware support
• Background job processing with proper queue management
• Type-safe configuration management

Testing & Quality

• Hurl-based API testing - Real HTTP requests, no mocking complexity
• GitHub Actions integration - Automated testing on every change
• Improved code quality workflows - Security-first approach without legacy ESLint
• Enhanced deployment validation - Automatic health checks after deployment

Developer Workflow

• One-command setup - task docker-db-setup && task deploy-docker
• Instant testing - task test runs comprehensive API test suite
• File-based routing - Intuitive endpoint creation with zero configuration
• Smart deployment - Automatic service replacement and conflict resolution

📖 Documentation Highlights

New & Updated Pages

• Home - Compelling introduction with clear value proposition
• Getting Started - 30-minute tutorial from zero to production API
• Context Utilities - Comprehensive guide to all available utilities
• Folder Structure - Complete project organization documentation
• GitHub Actions CI/CD - Full CI/CD pipeline documentation
• Running in Docker - Enhanced local development guide

Accuracy Improvements

• Removed unused rxQuery documentation
• Verified all context utilities exist in codebase
• Updated folder structure to match actual implementation
• Enhanced examples with real-world use cases

🐛 Bug Fixes

• Fixed index creation errors in Foxx service setup (src/setup.js:109)
• Resolved scheduler task conflicts - Better error handling for existing tasks
• Improved Docker networking - Host network mode for reliable container access
• Enhanced deployment reliability - Better file exclusion and timeout handling

🔄 Migration Notes

From Circle CI to GitHub Actions

• Circle CI configuration removed
• GitHub Actions workflows provide equivalent functionality
• Enhanced features: automatic releases, better security, faster builds

Test Structure Updates

• API tests moved from .api-test/ to tests/hurl/
• Updated all documentation and scripts to reflect new structure
• Improved test organization and maintainability

Documentation Structure

• Wiki pages rewritten for clarity and accuracy
• All examples verified against current implementation
• Enhanced developer onboarding experience

🎯 What's Next

This release establishes Foxx Builder as a production-ready framework with:

• Enterprise-grade CI/CD out of the box
• Comprehensive documentation that actually helps developers
• Modern development workflow that scales from prototype to production
• Zero-configuration setup that Just Works™

Ready to build amazing APIs? Check out our updated Getting Started guide and see how you can go from zero to production in 30 minutes.

---

📊 Release Stats

• Files changed: 50+ across codebase and documentation
• Lines of documentation: 2000+ lines rewritten for accuracy and clarity
• New features: GitHub Actions CI/CD, enhanced context utilities
• Bug fixes: 5+ critical issues resolved
• Developer experience: Significantly improved with one-command workflows

Full Changelog: v2.3.0...v2.4.0

GraphQL Support

What's Changed

• feat: GraphQL support [beta] by @skitsanos

Creating GraphQL endpoints

Add graphql.js to your route path as did until now with HTTP verbs (get.js, post.js...). The minimal set options for your handler would just exposing schema:

module.exports = {
    schema: new GraphQLSchema({...})
);

GraphQL endpoint handler example

const {GraphQLString, GraphQLSchema, GraphQLObjectType, GraphQLList} = require('graphql');
const {query} = require('@arangodb');

const AuthorType = new GraphQLObjectType({
    name: 'Author',
    fields: {
        _key: {type: GraphQLString},
        name: {type: GraphQLString}
    },
    resolve: (_, author) =>
    {
        const result = query`
        FOR author IN Authors
        FILTER author._key == ${author._key}
        RETURN author
        `;
        return result.next();
    }
});

const ArticleType = new GraphQLObjectType({
    name: 'Article',
    fields: {
        _key: {type: GraphQLString},
        title: {type: GraphQLString},
        authorKey: {type: GraphQLString},
        author: {
            type: AuthorType,
            resolve: (parent) =>
            {
                const authorKey = parent.authorKey;
                const result = query`
                FOR author IN Authors
                FILTER author._key == ${authorKey}
                RETURN author
                `;
                return result.next();
            }
        }
    },
    resolve: (_, article) =>
    {
        const result = query`
        FOR author IN Authors
        FILTER author._key == ${article.authorKey}}
        RETURN author
        `;
        return result.next();
    }
});

module.exports = {
    schema: new GraphQLSchema({
        query: new GraphQLObjectType({
            name: 'RootQueryType',
            fields: {
                hello: {
                    type: GraphQLString,
                    resolve()
                    {
                        return 'world';
                    }
                },

                getArticle: {
                    type: ArticleType,

                    args: {
                        _key: {type: GraphQLString}
                    },

                    resolve(_, {_key})
                    {
                        const result = query`FOR article IN Articles
                            FILTER article._key == ${_key}
                            RETURN article`;
                        return result.next();
                    }

                },

                getAllArticles: {
                    type: new GraphQLList(ArticleType),
                    resolve()
                    {
                        const result = query`
                          FOR article IN Articles
                          RETURN article
                        `;
                        return result.toArray();
                    }
                }
            }
        })
    }),
    graphiql: true
};

Testing your endpoint with Hurl

POST {{URL}}/examples/graphql_demo

{
    hello

    getArticle(_key: "3704"){
        title,
        author {name}
    },

    getAllArticles {
        title
    }
}

v.2.1.20230102

• Added auth utility into module.context with encode, decode and isExpired methods to handle JWT tokens
• Routes can require JWT authentication:

module.context.use((req, res, next) =>
{
    if (req.path === '/' || req.path.match(/\/(login|signup)/igu))
    {
        next();
    }
    else
    {
        const {authorization} = req.headers;

        if (!authorization)
        {
            res.throw(403, 'Missing authorization header');
        }

        const token = authorization && authorization.split(' ')[1];

        try
        {
            const {auth} = module.context;

            if (auth.isExpired(token))
            {
                res.throw(403, 'The token is expired');
            }

            next();
        }
        catch (e)
        {
            res.throw(403, e.message);
        }
    }
});

• CircleCI flow updated to use Node 18

v2.0.20220626

What's new:

• New, cleaner, folder structure, basically everything moved into the src folder.
• Added docker-compose.yml and a few shortcuts listed in package.json so developers can start making and testing their APIs on docker
• Updated documentation
• Example of how to use Hurl for API testing, can be found in the .api-test folder.
• CircleCI integration to demonstrate how to run a pipeline for API testing.

Support for running Tasks and Scripts

Example of using runTask

/**
 * Run Google Analytics on each API endpoint request
 */

module.context.use((req, res, next) =>
{
    const {runTask} = module.context;
    runTask(
        'Google Analytics PageView recording',
        'ga',
        {
            clientId: req.headers['x-bb-client-request-uuid'],
            path: req.path,
            headers: req.headers
        });

    next();
});

Session enabled API building

Added support for Session Manager middleware that works via HTTP headers.

To enable it, just add the following into your index.js:

const sessions = require('./sessions/index');
/*sessions.allowedResources = [
    ...sessions.allowedResources,
    '/echo'
];*/
sessions.init();

Uncomment lines to allow more API endpoints to be accessible without authentication.

Basic login, logout, and signup operations are added as well.

Bare minimum to start creating your APIs

Minimal set that required to start building ArangoDB Foxx Microservices