IR
irwinrodriguez.dev
ES EN DE
Back to docs

Middleware

FoxServer's middlewares are parts of the host, written in X#, that process the request before and after it reaches your controller. They ship with the server and are switched on and configured from the manifest: JWT, request logging, SSE, webhooks, status, OpenAPI, JSON-RPC and MCP, among others.

Two details that save you an afternoon. There is no way to write a middleware from VFP: what your project can do is BeforeEndpoint and AfterEndpoint per controller, and the ApplicationLifecycle for what belongs to the whole project. And CORS is not a middleware: it is resolved before the chain, so it is not switched on or off with the rest.

JWT authentication

It protects the endpoints that do not carry public in their HELP. The client sends Authorization: Bearer <token> and the middleware validates it before your code runs.

In the manifest:

"middleware": {
  "auth": {
    "enabled": true,
    "type": "jwt",
    "secret": "<cifrado con middleware-set, nunca en claro>",
    "tokenexpirationseconds": 86400,
    "loginendpoint": "auth/login"
  }
}
The secret is stored encrypted auth.secret is kept encrypted, and written with foxserver middleware-set. A plaintext secret in the manifest makes the engine answer 500 ("not a valid Base-64 string"). Encrypting it needs the FoxServer.SecurityHelper coclass registered: the installer does it, and on a ZIP install you register bin\SecurityHelper.comhost.dll with the 32-bit regsvr32.

The login endpoint contract

This cannot be guessed, and it is where everyone gets stuck the first time: the token is issued by the middleware, not by your code. Your controller validates the credentials and tells the engine whether they are good; the engine signs the JWT.

The routeMust match middleware.auth.loginendpoint, and carry public in the HELP
The bodyCannot be empty
X-Auth-StatusExactly "true" or "false". No other value works
With "true"The JSON must carry an object in data, which forces "responseformat": "foxserver": the free format has no envelope
Inside dataThree mandatory fields: id, name and role. If one is missing or empty, there is no token
Everything else in dataTravels as an extra claim of the token, and is read with req.GetClaim()
On that endpointthis.Ok() and this.Fail() do not work: they build their own response and the header is lost, so the engine answers 406. There you use res.status(n).json(...)

The token that comes out carries sub (the id), name, role, iat, exp and the extra claims. iat and exp are RFC 7519 NumericDate, whole seconds, and their difference is exactly tokenexpirationseconds.

The login, in full:

pLogin: validating credentials so the middleware issues the JWT
PROCEDURE pLogin(req, res) HELP "POST: auth/login public"
    LOCAL loRes, loData, lcEmail, lcPassword, loR

    loRes = THIS.newObject("status,data,message")

    TRY
        * The raw body plus ParseJson: more control than req.json when
        * the body may not arrive at all.
        LOCAL loBody
        loBody = THIS.ParseJson(req.GetRawBody())
        IF ISNULL(loBody)
            loRes.status  = "error"
            loRes.message = "A JSON body is required"
            res.AddHeader("X-Auth-Status", "false")
            loR = res.status(400)
            loR.json(THIS.ToJson(loRes))
            EXIT
        ENDIF

        lcEmail    = LOWER(ALLTRIM(NVL(loBody.email, "")))
        lcPassword = ALLTRIM(NVL(loBody.password, ""))

        IF !THIS.CredentialsAreValid(lcEmail, lcPassword)
            loRes.status  = "error"
            loRes.message = "Invalid credentials"
            res.AddHeader("X-Auth-Status", "false")
            loR = res.status(401)
            loR.json(THIS.ToJson(loRes))
            EXIT
        ENDIF

        * The three fields are mandatory. Anything else you add to
        * loData travels as a claim of the token.
        loData      = THIS.newObject("id,name,role")
        loData.id   = ALLTRIM(users.USR_ID)
        loData.name = ALLTRIM(users.USR_NAME)
        loData.role = ALLTRIM(users.USR_ROLE)

        loRes.status  = "ok"
        loRes.data    = loData
        loRes.message = "Successful login"

        * This is the line that issues the token. The JWT is signed by
        * the middleware; nothing is generated here.
        res.AddHeader("X-Auth-Status", "true")
        loR = res.status(200)
        loR.json(THIS.ToJson(loRes))
    CATCH TO loEx
        loRes.status  = "error"
        loRes.message = loEx.Message
        THIS.LogFromException(loEx)
        res.AddHeader("X-Auth-Status", "false")
        loR = res.status(500)
        loR.json(THIS.ToJson(loRes))
    ENDTRY
ENDPROC

A protected endpoint: just leave out public

pMyProfile: a JWT-protected endpoint
PROCEDURE pMyProfile(req, res) HELP "GET: profile"
    LOCAL loRes

    * The middleware validated the token before getting here. The user
    * comes resolved, and extra claims are read one by one.
    loRes = THIS.newObject("id,name,role,company")
    loRes.id      = req.AuthenticatedUser.id
    loRes.name    = req.AuthenticatedUser.name
    loRes.role    = req.AuthenticatedUser.role
    loRes.company = req.GetClaim("company", "")

    RETURN THIS.Ok(loRes)
ENDPROC

And if the token is missing, expired or badly signed, the middleware answers on its own:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="foxserver", error="invalid_token",
                  error_description="The access token expired"
Content-Type: application/problem+json; charset=utf-8

{"type":"about:blank","title":"Unauthorized","status":401,
 "detail":"Invalid token","instance":"/profile","code":"unauthorized"}

The WWW-Authenticate header is the RFC 6750 one, and it tells the three cases apart: with no credential presented it carries no error=, which is what §3.1 requires. The body is Problem Details (RFC 9457), like every error the engine produces.

CORS

It answers OPTIONS preflight requests before they reach the controller, and adds the headers to every response. Configured in the manifest:

{
  "allowedorigins": "https://miapp.com,https://admin.miapp.com",
  "allowedmethods": "GET,POST,PUT,PATCH,DELETE,OPTIONS",
  "allowedheaders": "Content-Type,Authorization,X-Requested-With"
}
CORS is resolved before the middleware chain, so it does not appear in the list of the ones you switch on and off. And allowedorigins is not authentication: if you expose MCP or JSON-RPC without auth, the engine warns you at start-up.

Request logging

It writes every request into daily files, in the folder logging.path names. The file name is made of the prefix, the type and the date:

logging.path\
  api_Request_20260915.log     requests served
  api_Error_20260915.log       errors

The host log is a different one: logs\FoxServer_<date>.log, at the root of the installation, one per day, split at 10 MB and purged after 30. The level is set with FOXSERVER_LOG_LEVEL and the retention with FOXSERVER_LOG_RETENTION_DAYS.

The Windows Event Viewer does not receive your logs Not even in service mode. An entry is written there only if writing the log file itself fails, so that a logging failure does not go unlogged.

What you can write: the controller hooks

There is no API for writing a middleware from VFP, but every controller has two hooks that the engine calls around each of its endpoints. They are the place to open your tables and to close them.

BeforeEndpoint and AfterEndpoint: opening and closing the database
DEFINE CLASS ProductsController AS ApiController OLEPUBLIC

    * Before EACH endpoint of this controller.
    * Returning .F. cuts it off: the endpoint never runs.
    FUNCTION BeforeEndpoint(req, res)
        SET DELETED ON
        SET EXCLUSIVE OFF
        OPEN DATABASE (THIS.cPath + "data\shop.dbc") SHARED
        RETURN .T.
    ENDFUNC

    * After EACH endpoint, whether it went well or not.
    PROCEDURE AfterEndpoint(req, res)
        CLOSE DATABASES ALL
    ENDPROC

ENDDEFINE
They are per controller: there is no "root controller" with hooks for the whole project. What does belong to the whole project is the ApplicationLifecycle, which runs when the server starts and stops.

Next: Licensing →