DJ Adams

Knowledge and netiquette in today's AI era

2026-07-29T00:00:00Z

I'm walking in the cool mornings at the moment, as the problem with my right knee is preventing me from running right now, which is driving me bonkers.

View from the narrowboat stern this morning just before I set off on the walk.

On the walk this morning, I listened to a couple of episodes from two great podcasts I'm subscribed to - Hanselminutes and Soft Skills Engineering.

Knowledge engineering and lifecycle management

In Stack Overflow for the Agent Era - with VP of Product Alex Lato, Scott Hanselman talks to Alex Lato about how Stack Overflow is evolving, driven by, and perhaps driven towards, the agent substrate. It's a fascinating conversation between two experienced folks, and well worth a complete listen. What I took from this conversation is that we may see a new knowledge-related discipline emerging, or at least a stronger focus in that direction.

Scott and Alex talked a lot about knowledge provenance, reliability, attribution and ranking, which made me wonder about what knowledge engineering, perhaps knowledge lifecycle management, might look like today and tomorrow. This knowledge, and how agents source, relay, condense, combine and share it, is originally from the hard work of folks on Stack Overflow and in other communities sharing what they know, but how will that evolve when the layers of reuse coalesce over time?

One other fascinating aspect that Alex shared, and Scott picked up, is that in Stack Overflow's new venture here, agents, and their activities, are ultimately and strongly tied to human "owners", with the provenance - but more importantly reputation - that is part of that association.

Netiquette and how our connections are changing

In Soft Skills Engineering's Episode 520, hosts Dave Smith and Jamison Dance are entertaining and fun to listen to as usual, and the word "netiquette" is brought up in the context of what one should and should not do in today's era of AI assisted work.

Netiquette was originally an umbrella term for how to behave in the brave new world of Internet-based communication - for example how and when to use the To:, Cc: and Bcc: in email correspondence (on which I have thoughts too), when to reply, and how formal, or not, one should be, in various situations. That concept of "how to behave" surfaces in this conversation again where Dave and Jamison talk about their (and others') experiences with folks copy-pasting wads of generative AI output to each other, sometimes without even reading it themselves.

Following that train of thought, they reach a conclusion that is not an entirely pleasant one, that the LLM facilities we have at our fingertips today is causing the death of the human connection, a connection that originally evolved (in our tech workplaces) almost as a by-product of collaborating on design and code, to get it right. When we have LLMs do a lot of that for us, where's the context in which we maintain that loose but essential human connection - the shared jokes, the gently snarky but well-meaning asides?

If you're not subscribed to these podcasts, I recommend you remedy that today!

Timeless principles, agnostic design and the power of CAP's abstractions

2026-07-24T00:00:00Z

I wrote recently about Hexagonal Architecture, alternatively known as Ports & Adapters, in Book Overflow and two architectural patterns in CAP. The core idea is based on having a deliberately agnostic approach to mechanisms, resources and services beyond - located in the outer concentric circles, as it were - a given core service.

Think of this in a similar way to "late cut" integration, where the actual location, shape of, and connection to a required service is left until the last minute.

The agnostic design approach is not new, and indeed as Daniel mentions in his keynote, has in the past been referred to as "minimal assumptions", which crops up in various disciplines, including statistics & data analysis, where it conveys the approach of "deriving valid conclusions using the fewest possible restrictive parameters"¹.

This approach brings many advantages, not least the ability for CAP developers to enjoy a tight and rapid development loop, where local-first is the mantra, and mocking plus remote proxies are key enablers.

Moreover it allows us to shift left the important business of design, including auth, consumption nuances and extended domain design, exactly because we can shift right the dirty work of connectivity and gnarly setups.

But that's only one half of the story. The other half is that, right from the get-go, we're ready to adapt and adopt new services, or different endpoint locations, because we haven't tightly coupled our app or service design with a specific technology or protocol.

The wonder of cds.service.bindings

To illustrate this, I want to convey the wonder of one of Daniel's live demos in the keynote. Indeed, this blog post was triggered by something very specific, when Daniel accessed cds.service.bindings in the cds REPL.

I have talked about the local service binding registry (~/.cds-services.json) and explained its purpose, in many places, including:

CAP local development (workshop)
Service integration with SAP Cloud Application Programming Model (CodeJam)
A hands-on tour of CAP (CodeJam)

Let's break down what we mean by "local service binding registry":

local: it's local to my machine, both highlighted and constrained by the location of this file, the developer user's home directory² - you can't get much more "my machine" specific than that!
service: required services, that are likely going to be remote in a production scenario
binding: information that is needed to be able to connect and authenticate with such services, such as URL & credentials, often collected into a destination in production scenarios
registry: a sort of table of contents, or list of what's currently available

Such a local registry is at the heart of how agnostic design's innermost set of concentric circles (the local machine) can function in CAP.

Seeing Daniel retrieve this binding information directly in the cds REPL was a magic moment for me. It both elevated the combined concepts I've mentioned above, plus made the registry content tangible and thus worthy of attention.

Exploring the first two circles

Let's explore the two innermost circles³, the ones within the local machine.

 +--------------------------+
 |     external process     |
 | ************************ |
 | * +------------------+ * |
 | * | separate process | * |
 | * |  +------------+  | * |
 | * |  | in-process |  | * |
 | * |  |            |  | * |
 | * |  +------------+  | *<---- local machine
 | * +------------------+ * |
 | ************************ |
 +--------------------------+

We can run a single CAP server, that will serve one or more services, via one or more protocols. That's denoted by the core "in-process" circle in this diagram here. When we have a required service without service bindings available, these are mocked also by the same CAP server.

At this point I often refer to the help text for the --with-mocks option for cds serve which goes like this (emphasis mine):

Use this in combination with the variants serving multiple services. It starts in-process mock services for all required services configured in package.json#cds.requires, which don't have external bindings in the current process environment. Note that by default, this feature is disabled in production and must be enabled with configuration features.mocked_bindings=true.

We can run multiple CAP servers on the same machine, choosing different ports⁴. From the perspective of the "in-process" innermost circle, the next circle out, marked "separate process", represents these other CAP servers.

This "local machine" universe, combined with CAP's local-first affordances, is exactly what we need to experiment with agnostic design here.

This demo follows roughly the same path as Daniel took in his keynote, with some slight variations.

Start monitoring the local service binding registry

It's helpful to see what happens as things progress, so let's use one terminal window to keep an eye on the local service binding registry's contents. Here's how I would do it:

touch ~/.cds-services.json \
  && watch -c jq -C . ~/.cds-services.json

I use touch first to make sure the file exists before trying to monitor it; this command will create the file, empty, if it doesn't. If it has already been populated with information from previously running CAP servers (that have since been stopped) then it may already contain some empty registry structure that looks like this:
{
  "cds": {
    "provides": {},
    "servers": {}
  }
}

Create a simple CAP project A

First, let's create a simple tiny-sample facet based CAP project "A" then immediately launch a cds REPL and have the CAP server start up⁵:

cds init --add tiny-sample proj-A \
  && cds repl --run proj-A

Log output like this will be emitted:

Adding facet: tiny-sample

Successfully initialized CAP project
Continue with: code proj-A

Welcome to cds repl v10.0.3
[cds] - using bindings from: { registry: '~/.cds-services.json' }
[cds] - loaded model from 1 file(s):

  proj-A/srv/cat-service.cds

[cds] - connect to db > sqlite { database: ':memory:' }
  > init from proj-A/db/data/CatalogService.Books.csv
/> successfully deployed to in-memory database.

[cds] - using auth strategy { kind: 'mocked' }
[cds] - serving CatalogService {
  at: [ '/odata/v4/catalog' ],
  decl: 'proj-A/srv/cat-service.cds:1'
}
[cds] - server listening on { url: 'http://localhost:33475' }
[cds] - server v10.0.3 launched in 209 ms
[cds] - [ terminate with ^C ]

------------------------------------------------------------------------
Following variables are made available in your repl's global context:

from cds.entities: {
}

from cds.services: {
  db,
  CatalogService,
}

Simply type e.g. CatalogService in the prompt to use the respective objects.

So far, so (very) good. Notice that the CAP server is started on a random port, which is the default behaviour when running in a REPL context (as it's effectively more of a "throwaway" server that might be spun up to run some tests against).

Notice also that there's a service called CatalogService that's available.

Check the local service binding registry

In the registry, we now see something like this:

{
  "cds": {
    "provides": {
      "CatalogService": {
        "endpoints": {
          "odata": "/odata/v4/catalog"
        },
        "server": 58557
      }
    },
    "servers": {
      "58557": {
        "root": "file:///tmp/proj-A",
        "url": "http://localhost:33475"
      }
    }
  }
}

This tells us (and any CAP server running in the same binding context, i.e. this local machine) that there's a service called CatalogService that is provided. There's information on what the endpoints are, and what protocols these endpoints speak, and also the URL. In other words, this is the binding context for the CatalogService that is listed as being provided (note the cds.provides property that contains it)!

Connect and consume CatalogService locally

Within the REPL, if we now have a quick look at the CatalogService, we see that it's an instance of the ApplicationService class, effectively a locally available service:

> CatalogService
ApplicationService {
  handlers: [EventHandlers],
  name: 'CatalogService',
  options: [Object],
  kind: 'app-service',
  ...
  path: '/odata/v4/catalog',
  '$linkProviders': [Array]
}

We can consume that service directly, whereupon we'll get the result we probably expect:

> await CatalogService.read(`Books`)
[
  { ID: 1, title: 'Wuthering Heights', author: 'Emily Brontë' },
  { ID: 2, title: 'Jane Eyre', author: 'Charlotte Brontë' },
  { ID: 3, title: 'The Raven', author: 'Edgar Allen Poe' },
  { ID: 4, title: 'Eleonora', author: 'Edgar Allen Poe' },
  { ID: 5, title: 'Catweazle', author: 'Richard Carpenter' }
]

We can be explicit and connect to the service, a "required" service, like this, too:

> catsrv = await cds.connect.to('CatalogService')
ApplicationService {
  handlers: [EventHandlers],
  name: 'CatalogService',
  options: [Object],
  kind: 'app-service',
  ...
  path: '/odata/v4/catalog',
  '$linkProviders': [Array]
}

We effectively get the same ApplicationService instance, and can use it in the same way:

> await catsrv.read(`Books`)
[
  { ID: 1, title: 'Wuthering Heights', author: 'Emily Brontë' },
  { ID: 2, title: 'Jane Eyre', author: 'Charlotte Brontë' },
  { ID: 3, title: 'The Raven', author: 'Edgar Allen Poe' },
  { ID: 4, title: 'Eleonora', author: 'Edgar Allen Poe' },
  { ID: 5, title: 'Catweazle', author: 'Richard Carpenter' }
]

Consume the provided service from elsewhere

We don't even need to set up a second project to require (consume) this provided service, we can just start a second cds REPL session and do everything there.

While keeping the current cds REPL session open, let's start a second cds REPL session in a new terminal window. This should represent a distinctly separate CAP consumer context and so let's start this second cds REPL session completely separate from the proj-A/ area to emphasise that point. Daniel used his home directory for that, so let's do that too:

cd ~ && cds repl

Fetch the service bindings

In the session that we get, which is announced like this:

Welcome to cds repl v10.0.3
>

we can access the service bindings, like this:

await cds.service.bindings

This fetches the service bindings from the registry and makes them available in the current process:

[cds] - using bindings from: { registry: '~/.cds-services.json' }
Bindings {
  provides: {
    CatalogService: { endpoints: { odata: '/odata/v4/catalog' }, server: 58557 }
  },
  servers: {
    '58557': { root: 'file:///tmp/proj-A', url: 'http://localhost:33475' }
  }
}

We even see that log line familiar to us from our cds watch sessions, being explicit about from where the bindings are being fetched:

[cds] - using bindings from: { registry: '~/.cds-services.json' }

Connect to the service

Like we did in the other cds REPL session, let's now use cds.connect.to:

> cs = await cds.connect.to('CatalogService')
RemoteService {
  handlers: [EventHandlers],
  name: 'CatalogService',
  options: [Object],
  kind: 'odata',
  ...
  requestTimeout: 60000,
  csrf: undefined,
  csrfInBatch: undefined
}

This time, it's not an instance of the ApplicationService class, it's an instance of the RemoteService class!

Send a query to the service

What's more, we can interact with that service ... as if it were local:

> await cs.read(`Books`)
[
  { ID: 1, title: 'Wuthering Heights', author: 'Emily Brontë' },
  { ID: 2, title: 'Jane Eyre', author: 'Charlotte Brontë' },
  { ID: 3, title: 'The Raven', author: 'Edgar Allen Poe' },
  { ID: 4, title: 'Eleonora', author: 'Edgar Allen Poe' },
  { ID: 5, title: 'Catweazle', author: 'Richard Carpenter' }
]

Wham!

Wrapping up

Going back to the concentric circles, this is a effectively an example of the two that are within the confines of the local machine. One, the provided service, exists as if it were remote (with a URL) in the eyes of the consuming service (or REPL context here).

CAP's adoption of minimal assumptions in service provision and consumption is so complete that the lines become blurred between local and remote, thanks to the power of remote proxies that do the heavy lifting of query transport across the wire for us.

This really is hard evidence of one of CAP's "magic made simple" moments, and is explained further in the CAP-level Integration section of the Bookshop topic in Capire.

Footnotes

See Non-Linear Regression with Minimal Assumptions
The symbol for a user's home directory is the tilde (~). I'm guessing some of you know why it's this symbol, but for those of you who don't, have a look at the keyboard of the ADM-3A terminal, specifically in the top right. Bill Joy, erstwhile employee of Sun and perhaps more importantly creator of both vi and the C Shell (csh), used an ADM-3A and it was in the C Shell where the tilde came to represent a user's home directory.

Also on that same key is the caret (^), which also represents "home" (beginning of a line) in regular expression dialects. Coincidence? I think not! :-)
OK, it may not have escaped your notice that these are not circles. Just pretend they are.
It's the concept of a socket that we must bear in mind, which is the combination of protocol, address (hostname / IP) and port. But that's a story for another time.
We can actually just specify the project location as a single argument and the same thing will happen: cds repl proj-A.

reCAP 2026 talk resources

2026-07-15T00:00:00Z

At reCAP this year, I was honoured to share a talk slot with Patrice Bender, a good friend and adjacent colleague from the CAP Compiler team, and cohost / copresenter on the Hands-on SAP Dev mini-series on the core expression language in CDS.

The talk was titled Expressions and Abstractions - Two Developer Superpowers in CAP, with the following overview:

Today we need to be more efficient and concise than ever, stop writing code we don't need to, and avoid tasks that slow down our development loops, letting the framework do the heavy lifting for us. In this session we'll demonstrate two different affordances that enable that. First, we'll show the power of expressions, what they are, how and where they can be used, and why you should know about them. Then we'll show how mocking abstracts us from the tedium and ceremony, allowing us to iterate fast on data, auth, messaging and remote services during development.

Whether you watched the talk at reCAP in person, or remotely, please consider filling in the short feedback form. Thanks!

Here are some resources relating to the two parts.

Expressions

The demo resources used in this part of the talk are available in the repo cxl-bookshop that is an extended bookshop you can clone, open in cds repl, and use to try everything shown live.

The talk is based on the 7-part Hands-on SAP Dev mini-series Under the hood: CDS Expressions in CAP, with our written notes accompanying it, starting with Part 1. For the reference, including syntax diagrams that show what an expression can contain, see the CXL topic in Capire.

Abstractions

The demo resources used in this part of the talk are available in the repo cap-nodejs-local-first-development.

The Local-first dev with CAP Node.js series of blog posts covers mocking of data, auth, remote services and messaging.

In the content for the CodeJam A hands-on tour of CAP there are deep and detailed dive exercises on mocking auth and mocking messaging. At the end of each of these exercises are plenty of links to further information including resources in Capire.

Computing memories

2026-07-08T00:00:00Z

My good friend and colleague Antonio shared some thoughts today (also, see update below) about a post he'd just read: The Last People Who Know How It Works.

I was composing a reply to Antonio's thoughts on LinkedIn, but then thought better of it, and in the proper spirit of "owning (and being in control of) one's own content", harking back to the good old days of communication and community on the Web, I thought I'd write my reply here and then point to it via a URL. So here goes.

The post is a lovely read, and makes a great point that resonates with me, a point about the potential (or imminent) loss of knowing how things work, through having to make things work. I have many memories of building things from scratch, making computers do things (where in their default state they would do nothing).

For our SAP community readers, I also remember (in the early to mid 1990's) calculating which actual magnetic tracks across which cylinders (physical partitions on the DASD) to place different parts of the SAP R/2 document database and indices (ABEZ, ABIB, etc) for optimal head movement across the spinning platters. Most commonly we'd use IDCAMS to define VSAM Data Sets.

I'm sure that many of you dear readers have equivalent and equally fond memories.

One thing that stood out in the post was this wonderful image:

I went looking the other night for a recording of a modem connecting. People keep them around like pressed flowers.

Such sounds are indeed, at least in my mind, delicate artifacts, and worth preserving. And preserving with care.

One statement the post makes is:

A machine that cannot challenge you is a thing you cannot know. You can only use it.

I agree strongly with this. It summarises much of how I feel about using computers, and reminds me of the TEDx talk I gave back in 2012 titled Our Computational Future, on how we should not be raising generations of users, but generations of creators and builders.

Here's something else from the post:

The knowledge is not in danger, in fact, it has never been safer. The AI models have read every manual that no human reads.

Now this I cannot agree with, in fact strongly disagree (based on the way I read it, which may be incorrect). We have been down those roads of information being lost to time, either due to deterioration of physical media, or due to proprietary formats where there's no way of reincarnating a reader program. If we're relying on AI to remember stuff for us, that's very short sighted. Who owns the models, the systems, the processes? What format is that stored in, and how accessible is that to everyone and anyone who wants it?

That road is a road to pain and regret.

Anyway, I don't want this last thought to take anything away from the post - it's still a lovely read.

Update: Antonio has put his thoughts on his own post now too, kudos: A simple reflection on how things work, curiosity and friction.

Blogging in en-GB

2026-07-04T00:00:00Z

Terence Eden recently published a post titled This blog is written in en-GB. Before I even read the post, I knew what it was going to be about, and that I had to make that change myself too, for the same reasons as I'd guessed he was going to explain.

Terence expresses those reasons very well, so I won't try to reproduce them here. I'm in strong agreement with him and those reasons resonate with me. This is my blog, I string all the words together, in my own style, on the topics I choose, with or without bias, depending on what I think. That is called a voice. Everyone has one, this is mine.

To ask someone to change that (as a commenter did, to Terence), is not only poor judgement, it is also self-centred. It reminds me of how I sometimes feel about people who get "offended". Offence is taken, not given. Indeed, as Ricky Gervais famously said "just because someone is offended, it doesn't mean they're right".

I attribute much of my learning by coming across references or ideas that I didn't quite understand, and looking them up. Today, that's easier than ever. To ask someone to make their cultural references more "accessible" is asking to be spoon fed slop.

Talking of slop, one thing that gives me hope in today's world of generated content, is that the human experience as expressed by individuals is what will keep us sane. If you want more on that, I recommend the post The best response to AI slop, infinite advice, and online noise is from Robin Williams.

In turn, that post reminded me of the classic quote:

"The computer can't tell you the emotional story. It can give you the exact mathematical design, but what's missing is the eyebrows."

If you don't know who uttered that ... go and find out.

CAP service authentication at design time and in production

2026-06-19T00:00:00Z

Recently I wrote about mocking auth in CAP for a rapid local-first development loop that allows you to embrace auth design rather than defer it to later.

In development mode, unless otherwise stated (i.e. unless you add appropriate annotations such as @readonly, @requires or @restrict), all resources are accessible to everyone, even without authenticating. This is appropriate and fitting, helping to facilitate the tight feedback loop that folks love when developing with CAP.

What about production? Is it the same there, i.e. do we have to ensure we lock down access before moving to production? Of course not. Here's how things work.

Default auth settings for development

In development mode, the default auth strategy is "mocked", as we can see:

; cds env requires.auth
{
  restrict_all_services: false,
  kind: 'mocked',
  users: {
    alice: { tenant: 't1', roles: [ 'admin' ] },
    bob: { tenant: 't1', roles: [ 'cds.ExtensionDeveloper' ] },
    carol: { tenant: 't1', roles: [ 'admin', 'cds.ExtensionDeveloper' ] },
    ...
    yves: { roles: [ 'internal-user' ] },
    '*': true
  },
  tenants: { t1: { features: [ 'isbn' ] }, t2: { features: '*' } }
}

Notice also the restrict_all_services property, which is set to false by default in development mode too.

This property is at the core of the "failsafe" production auth mechanism that means that even if you do nothing with regards to auth for your services, they will be protected in production and only available to users who provide appropriate authentication.

Default auth settings for production

In the Authentication in Production section in Capire, we read, in the "Enforced by Default" subsection:

In a productive scenario with an authentication strategy configured, for example the default jwt, all CAP service endpoints are authenticated by default, regardless of the authorization model. That is, all services without @restrict or @requires implicitly get @requires: 'authenticated-user'.

This can be disabled via feature flag cds.requires.auth.restrict_all_services: false, or by using mocked authentication explicitly in production

We can check that the default auth strategy is jwt in production, like this:

; NODE_ENV=production cds env requires.auth
{ kind: 'jwt', vcap: { label: 'xsuaa' } }

Notice also here that restrict_all_services is not there, and will thus have an undefined value:

; NODE_ENV=production cds env requires.auth.restrict_all_services
undefined

Understanding the mechanism

Now we understand the background, let's dig in to see how this works, to understand things better.

In the runtime, there's @sap/cds/lib/srv/protocols/https.js, which contains:

const cds = require('../../index'), { decodeURI } = cds.utils
const express = require('express')
const PROD = process.env.NODE_ENV === 'production'
const restrict_all = cds.env.requires.auth?.restrict_all_services !== false
const authenticated = PROD && restrict_all ? ['authenticated-user'] : false

class HttpAdapter {

  // ...

  /**
   * Returns a handler to check required roles, or null if no check required.
   * @returns {express.RequestHandler|null}
   */
  get requires() {
    const d = this.service.definition; if (!d) return null
    const rr = d['@requires'] || d['@restrict']?.map(r => r.to).flat().filter(r => r)
    const roles = !rr?.length ? authenticated : Array.isArray(rr) ? rr : [rr]
    return super.requires = roles && function requires (req, res, next) {
      const user = cds.context.user
      if (roles.some(role => user.has(role))) return next() //> ok
      else if (user._is_anonymous) return next(401) //> request login
      else cds.error (403, `User '${user.id}' is lacking required roles: [${roles}]`)
    }
  }

  // ...
}

module.exports = HttpAdapter

This is from a @sap/cds runtime version 9.9.1 at the time of writing.

If we stare at this for a moment, we see that:

authenticated is set to the value ['authenticated-user'] if we're in production and the restrict_all_services value is NOT explicitly set to false
then, in the handler that gathers and checks for the specific roles required when a resource is requested, if there are no roles explicitly set as required for the service, then this authenticated-user role is used (remember, authenticated-user is a pseudo-role)

In other words, if you haven't set a value explicitly for restrict_all_services then this will "fail safely" in production.

Wrapping up

So there you have it. I mean, it's sort of obvious when you think about it, but I think it's always nice to "understand by reading" and spend a bit of time to dwell on the mechanism.

Book Overflow and two architectural patterns in CAP

2026-06-04T00:00:00Z

Book Overflow is "a long-form discussion podcast for software engineers" and one of the shows to which I'm subscribed.

The recent episode 118 is one in the series where Carter and Nathan discuss the book Learning Domain-Driven Design: Aligning Software Architecture and Business Strategy by Vlad Khononov.

I listened to this episode today and found that, as usual, the two go into great depth and draw on their thoughtfulness and experience to tease out details and connect the dots for us listeners.

Covered in their discussions were a couple of patterns that resonated with me:

Ports And Adapters
Transactional Outbox

Both these patterns live and breathe strongly within CAP, from a philosophical standpoint but also from a place that drives the fundamental design of the framework and how it manifests for us developers. So I thought it would be worth both highlighting this episode, series, and podcast, while also connecting the patterns and where they are in CAP.

Ports and adapters

The Ports And Adapters pattern is another name for Hexagonal Architecture, brought into this world and popularised by Alistair Cockburn. It's the ultimate approach to making agnosticism and abstraction first class players in system design.

(Nathan playfully observed that the hexagon isn't really used to the max, with only four sides used in the illustration. I may be misremembering, but I think Alistair might have picked the hexagon as it was different from other boxy shapes available in a classic software diagramming template he had to hand, plus the "extra" sides lend themselves to further expansion by folks using the diagram to express their own usage of the pattern.)

Of course, we know that Hexagonal Architecture is a core concept in CAP, one that supports CAP's agnostic-by-design approach to pretty much everything. It also is a fundamental enabler of the CAP developer experience - grow as you go for rapid prototyping with mocks followed by a seamless transition to production grade services when appropriate.

Transactional outbox

The Transactional Outbox pattern is one that we see reminders of while developing, with the built-in outbox table. This pattern allows the coordination of a typical enterprise scenario where data needs to be updated and an event needs to be sent to a remote system.

The requirement to have both (synchronous and asynchronous) parts as a transactional unit presents challenges, but by deferring the actual delivery of the event to a separate service, the two parts can coalesce and indeed be treated as a unit that collectively either works or doesn't.

Facilitating this is an "outbox" for events, which is at the heart of this pattern, and which CAP has had for a few years now.

Local-first dev with CAP Node.js - mocking messaging

2026-05-15T00:00:00Z

This post is one of a series on local-first development with CAP Node.js.

Everything is an event

In Five reasons to use CAP, we see that everything is an event. Whether synchronous, such as via HTTP requests and responses for OData operations, or asynchronous, where messages are emitted and received for decoupled service-to-service communications.

The Messaging topic in Capire has a great overview and an explanation of all the different message brokers that can be used. And there's one that is well suited for local-first development: File based messaging.

Working through an example

In this post, we'll work through an example of mocking messaging using the file-based facility, with content in the messaging/ directory of the repo set up for the related talk.

The setup is a little different to the other mock examples in this series. First, there are two CAP services that will be in play. Second, neither of them have any entity definitions; in fact, only one has a CDS model at all, and that only has a service definition with an action and an event defined within it.

The containing project definition

Usually in an asynchronous event scenario there is an emitter and a receiver, and that's what we have here. They're both found within the messaging/ directory, which is the containing project for this example, and has been set up to use the Node.js workspaces concept, with this as the definition in package.json:

{
  "name": "@qmacro/messaging",
  "workspaces": [
    "*"
  ]
}

Examining the emitter

Within the emitter/ subdirectory we have a CAP project which has been put together in the form of a package (like a plugin would be). The name declared in emitter/package.json is @qmacro/emitter and as well as the content in srv/ there's also a project root level emitter/index.js which acts as the package entry point and contains:

using from './srv/main';

The emitter service definition

This emitter is where the service definition is found, which looks like this, in emitter/srv/main.cds:

namespace org.qmacro.emitter;

@rest
service EmitterService {
  action greet(greeting: String) returns String;

  event Greeting.Received {
    info : String;
  }
}

The service defines:

an action endpoint greet
an event Greeting.Received

Note that while the term "action" has loaded meaning in the context of OData, it also serves to define a POST based "RPC" style target that is valid even in the context of the "REST" protocol, as declared here. The design of the event and also the signature of the action endpoint is deliberately as simple as possible for this example.

As we'll see shortly, to have an event be emitted in this example scenario, we need to make an HTTP POST request to the /greet endpoint, with a payload body containing the greeting data.

The emitter service implementation

Every action definition needs an implementation, and this is what we have in emitter/srv/main.js:

const cds = require('@sap/cds')
const log = cds.log('emitter')

module.exports = cds.service.impl(async function() {
  this.on('greet', async (req) => {
    const emitter = await cds.connect.to('org.qmacro.emitter.EmitterService')
    log(`emitting Greeting.Received (${req.data.greeting})`)
    await emitter.emit('Greeting.Received', { info: req.data.greeting })
    return 'OK'
  })
})

And that's pretty much it!

Messaging configuration

But upon what messaging mechanism are we relying here? Well, that's defined as a requirement in the emitter's emitter/package.json:

{
  "name": "@qmacro/emitter",
  ...
  "cds": {
    "requires": {
      ...
      "messaging": {
        "kind": "file-based-messaging"
      }
    }
  }
}

The value file-based-messaging is what we want here, as described in the corresponding Capire section where it tells us that a file is used as the message broker; that is, the emitter writes messages to the file, and the receiver reads (and then removes) messages from that file.

By default the file is ~/.cds-msg-box. This fits with the general approach of using hidden files in the developer's home directory (~/.cds-services.json is another example), emphasising the point that this is design-time only, i.e. only for used in a local development context.

Examining the receiver

The receiver in this setup is even simpler. It relies upon the emitter package, and defines it as a required service, in receiver/package.json:

{
  "name": "@qmacro/receiver",
  ...
  "dependencies": {
    "@qmacro/emitter": "*"
  },
  ...
  "cds": {
    "requires": {
      ...
      "EmitterService": {
        "service": "org.qmacro.emitter.EmitterService",
        "model": "@qmacro/emitter"
      },
      "messaging": {
        "kind": "file-based-messaging"
      }
    }
  }
}

Like the emitter, it also defines a requirement on file-based-messaging.

The receiver implementation

There's no CDS model in this simple receiver setup, just an implementation that is in the form of a custom server in receiver/server.js:

const cds = require('@sap/cds')
const log = cds.log('receiver')
const eventID = 'Greeting.Received'

cds.once('served', async () => {
  log(`Setting up listener for ${eventID}`)
  const EmitterService = await cds.connect.to('EmitterService')
  EmitterService.on(eventID, (msg) => {
    log('received:', msg.event, msg.data)
  })
})

Once the CAP server has started up, a connection to the emitter service is made and a handler is registered for the Greeting.Received event.

And that's all we need!

Trying it out

We can try the entire construct out step by step to see what's going on. All the following invocations are based on being in the messaging/ project root directory.

Before we start, we'll install the dependencies from the project root with:

npm install

Starting up the emitter

Now, let's start the emitter up, and we'll specify DEBUG level for the queue component(s) for a more detailed insight as to what happens:

DEBUG=queue cds watch emitter

We should see some familiar log output (some lines have been omitted for brevity):

[cds] - using bindings from: { registry: '~/.cds-services.json' }

[queue] - Using non-scheduling-based event queue processing
[cds] - connect to messaging > file-based-messaging
[cds] - serving org.qmacro.emitter.EmitterService {
  at: [ '/rest/emitter' ],
  decl: 'emitter/srv/main.cds:4',
  impl: 'emitter/srv/main.js'
}
[cds] - server listening on { url: 'http://localhost:4006' }

The file-based-messaging mechanism is brought into play, just before our emitter service is served.

Port 4006 is selected by means of the value in emitter/.env; it has no special significance, except that it's one of a few ports (4004-4006 and 9229) that I publish in my dev container in which I do all my work.

The service is registered in the local development binding registry ~/.cds-services.json:

{
  "cds": {
    "provides": {
      "org.qmacro.emitter.EmitterService": {
        "endpoints": {
          "rest": "/rest/emitter"
        },
        "server": 35678
      }
    },
    "servers": {
      "35678": {
        ...
      }
    }
  }
}

As we've seen in another blog post in this series, on mocking remote services, this registry serves to provide information on services provided and required.

Invoking the greet action

Normally at this point it would make sense to start up the receiver, to have the fully coordinated asynchronous setup. But we want to see things happen step by step, and if we were to start the receiver now, any message generated and emitted would be immediately consumed and we wouldn't see it "in transit".

So at this point we'll invoke the greet action that the emitter exposes, to have a message emitted.

curl \
  --url "localhost:4006/rest/emitter/greet" \
  --data '{"greeting":"Understanding is everything!"}'

From this, we get a simple OK, as we'd expect from the emitter service implementation. More interesting is what we see in the server log:

[rest] - POST /rest/emitter/greet
[emitter] - emitting Greeting.Received (Understanding is everything!)
[persistent-queue] - queue: Write message to queue
[persistent-queue] - queue: Fetch messages
[persistent-queue] - queue: Process 1 message
[persistent-queue] - queue: Messages modified (-1, ~0, +0)
[persistent-queue] - queue: Done

While the [rest] log record is just recording the incoming POST request, and the [emitter] log record was written by the emitter implementation (see above), most notably we see the core messaging mechanism in action, handling the queuing of the message. After all, queueing is a core part of everything that is asynchronous.

Looking at the message queue

As we know, the file based messaging uses ~/.cds-msg-box by default as the queue. And if we look at that right now:

cat ~/.cds-msg-box

we see the message, "in transit", as it were (formatted here for easier reading):

org.qmacro.emitter.EmitterService.Greeting.Received {
  "data": {
    "info": "Understanding is everything!"
  },
  "headers": {
    "x-correlation-id": "80f83122-ecb7-49aa-8cdd-c465e2588374"
  }
}

Half-way there!

Starting up the receiver

Now we've had a chance to examine the queue, we can start up the receiver:

cds watch receiver

[cds] - bootstrapping from { file: 'receiver/server.js' }
...
[queue] - Using non-scheduling-based event queue processing
[cds] - connect to messaging > file-based-messaging
...
[receiver] - Setting up listener for Greeting.Received
[cds] - server listening on { url: 'http://localhost:4005' }

And directly following this, we see:

[receiver] - received: Greeting.Received { info: 'Understanding is everything!' }

Not only that, but the queued message in ~/.cds-msg-box is now gone. Consumed!

Wrapping up

Asynchronous messaging is yet another fundamentally important aspect of real life service design, delivery and orchestration, and we have no reason to put off designing and building that in our projects, as we can incorporate local mocking from the very start.

By the way, for automated tests, you might even want to look at local messaging which takes place in-process, a little bit like in-process remote-service mocking, and is very useful for automated testing.

Local-first dev with CAP Node.js - mocking remote services

2026-05-13T00:00:00Z

This post is one of a series on local-first development with CAP Node.js.

Calesi and mocking remote services

In the context of CAP-Level Service Integration (aka "Calesi") we can mash up remote and local services, and in the full spirit of CAP generally, run everything in airplane mode, i.e. fully locally.

Working through an example

In this post, we'll work through an example of mocking a remote service, based on content in the remoteservice/ directory of the repo set up for the related talk.

We start with an almost empty project directory, save for a basic package.json file which we only really have at this point so we can check the changes in it that are introduced when we import a remote service API definition. All operations are done in the context of this project directory.

The other files in this directory in the repo are related to performing and resetting the demo during the talk version of this post.

Examining and importing the candidate remote service

At https://odd.cfapps.eu10.hana.ondemand.com/ there's the northbreeze OData V4 service with Products, Categories and Suppliers¹. The service's API is available as the metadata document so let's grab that:

curl \
  --url 'https://odd.cfapps.eu10.hana.ondemand.com/northbreeze/$metadata' \
> northbreeze.edmx

and use cds import to import it to our project:

cds import northbreeze.edmx

This emits:

[cds] - updated ./package.json

[cds] - imported API to srv/external/northbreeze
> use it in your CDS models through the likes of:

using { northbreeze as external } from './external/northbreeze';

and the EDMX API definition, along with the CAP-focused CSN equivalent that was created at import, are moved into an external/ directory within a standard srv/ directory (which itself is autovivified at this point):

./
├── package.json
└── srv/
    └── external/
        ├── northbreeze.csn
        └── northbreeze.edmx

Mocking is automatically and immediately initiated

At this point too, the CAP server restarts and shows:

[cds] - loaded model from 1 file(s):

  srv/external/northbreeze.csn

[cds] - using bindings from: { registry: '~/.cds-services.json' }
[cds] - connect to db > sqlite { url: ':memory:' }
/> successfully deployed to in-memory database.

[cds] - mocking northbreeze {
  at: [ '/odata/v4/northbreeze' ],
  decl: 'srv/external/northbreeze.csn:170'
}
[cds] - server listening on { url: 'http://localhost:4004' }

This is because cds watch is actually shorthand for:

cds serve all --with-mocks --in-memory?

and if we read the help for --with-mocks we see this:

Use this in combination with the variants serving multiple services.

It starts in-process mock services for all required services configured in package.json#cds.requires, which don't have external bindings in the current process environment.

Note that by default, this feature is disabled in production and must be enabled with configuration 'features.mocked_bindings=true'.

That's right - mocking is already being done for our imported remote service! It's in-process, i.e. within the same CAP server process that we started with cds watch.

The package.json file is extended

As part of the import process, package.json was modified in two key areas:

--- a/remoteservice/package.json
+++ b/remoteservice/package.json
@@ -4,7 +4,10 @@
   "description": "Demonstrating local-first support for remote services",
   "dependencies": {
     "@sap/cds": "^9",
-    "express": "^4"
+    "express": "^4",
+    "@sap-cloud-sdk/connectivity": "^4",
+    "@sap-cloud-sdk/http-client": "^4",
+    "@sap-cloud-sdk/resilience": "^4"
   },
   "devDependencies": {
     "@cap-js/sqlite": "^2"
@@ -12,5 +15,13 @@
   "scripts": {
     "start": "cds-serve"
   },
-  "private": true
-}
+  "private": true,
+  "cds": {
+    "requires": {
+      "northbreeze": {
+        "kind": "odata",
+        "model": "srv/external/northbreeze"
+      }
+    }
+  }
+}

the SAP Cloud SDK libraries were added - for marshalling of, connection to and communication with remote destinations²
the remote service is added as "required", with the name northbreeze

Reviewing the situation

This in-process mocking of the required remote service "northbreeze" means that in the CAP server context that exists for our project, we have that remote service as an endpoint available to us at http://localhost:4004:

But while the mocked remote service is already fully formed, even in this "in-process" mode, there's no data. Let's add some so we can better explore the service.

Add data for the mocked remote service

Using CAP's mock data facilities, we can easily come up with some mock data. Because of CAP's convention over configuration axiom, this works even for mocked remote services. As an erstwhile Perl programmer, I appreciate this DWIM-style approach.

To dig in more to the mock data facilities in CAP, see the mocking data blog post in this series.

Have some data generated

Let's first have CAP generate some data for us:

cds \
  add data \
  --filter Categories \
  --records 10

This creates a CSV file with an appropriate name and in the expected place for initial data:

./
├── db/
│   └── data/
│       └── northbreeze.Categories.csv
├── package.json
└── srv/
    └── external/
        ├── northbreeze.csn
        └── northbreeze.edmx

Retrieve data and use that too

Given this is about gathering some data to exercise the mocked remote service, it's likely that the actual remote service has data that we can perhaps use too.

Being an OData V4 service, the data available, in the form of, say, an entityset, is going to be in JSON format by default. But that's fine, the CAP server's data mechanism can deal with this too. So let's grab the Products data from the actual remote service and place it alongside the Categories data we have:

curl \
  --silent \
  --url 'https://odd.cfapps.eu10.hana.ondemand.com/northbreeze/Products' \
| jq .value \
> db/data/northbreeze.Products.json

We can mix CSV and JSON data with ease:

./
├── db/
│   └── data/
│       └── northbreeze.Categories.csv
:       └── northbreeze.Products.json

and it's picked up as we would hope:

[cds] - connect to db > sqlite { url: ':memory:' }
  > init from db/data/northbreeze.Products.json
  > init from db/data/northbreeze.Categories.csv
/> successfully deployed to in-memory database.

Move the data closer to the service

While the data for this mocked external required service is perfectly fine in db/data/ and is picked up as we'd expect, perhaps it makes more sense to keep it closer to the service definition, as a "bundle", as it were. That will work too, with respect to the automatic data loading mechanism, so let's do that:

mv db/data/ srv/external/

Now the external service is more self-contained:

./
├── db/
├── package.json
└── srv/
    └── external/
        ├── data/
        │   ├── northbreeze.Categories.csv
        │   └── northbreeze.Products.json
        ├── northbreeze.csn
        └── northbreeze.edmx

Switching to a more realistic scenario

There are a couple of aspects we should look at now, based on the very simple setup we have so far:

the required remote service has been mocked in-process; ideally we want a local development scenario that is closer to the eventual production situation
it is also entirely independent, unrelated to any local service definitions

Regarding the first aspect, we can also have a service mocked in a separate process, instead of being mocked in-process. One effect of this is that real wire API calls are made between your local service and the separately mocked (but still locally running) remote service.

Regarding the second aspect, we'll set up a local to remote proxy definition in our CDS model, for an entity. We'll do that first staying with in-process mocking, and then switch to separate process based mocking.

Set up a local to remote proxy definition

One of the simplest forms of service mashup is surfacing a remote entity as a local one. This may not be entirely useful, but it demonstrates the atomic structure of more involved scenarios, and is nice and simple so as not to get in the way of understanding here.

First, add the following service definition in srv/main.cds, remembering that the using directive here brings in the northbreeze scope from the imported remote service definition that was created with the cds import earlier:

using {northbreeze} from './external/northbreeze';

service Main {
  entity Products as projection on northbreeze.Products;
}

In the following sections, we'll see the difference between in-process and external process mocking.

Examine the CAP server logs now

Once the CAP server restarts, take a look at the log output:

[cds] - loaded model from 2 file(s):

  srv/main.cds
  srv/external/northbreeze.csn

[cds] - using bindings from: { registry: '~/.cds-services.json' }
[cds] - connect to db > sqlite { url: ':memory:' }
  > init from srv/external/data/northbreeze.Products.json
  > init from srv/external/data/northbreeze.Categories.csv
/> successfully deployed to in-memory database.

[cds] - serving Main {
  at: [ '/odata/v4/main' ],
  decl: 'srv/main.cds:3'
}
[cds] - mocking northbreeze {
  at: [ '/odata/v4/northbreeze' ],
  decl: 'srv/external/northbreeze.csn:170'
}

What we see is very useful and helps augment our understanding:

the overall CDS model is built from the local definition we've just created, plus the definitions from the remote service
initial data is being loaded from the CSV and JSON files
the local provided service Main is served
the remote required service northbreeze is also served, mocked in-process

Moreover, when we request a Products resource from the local Main service at /odata/v4/main, which as we know from our service definition is a projection onto the corresponding entity in the remote service definition:

curl --url 'localhost:4004/odata/v4/main/Products?$top=1'

we get a successful result:

{
  "@odata.context": "$metadata#Products",
  "value": [
    {
      "ProductID": 1,
      "ProductName": "Chai",
      "QuantityPerUnit": "10 boxes x 20 bags",
      "UnitPrice": 18,
      "Category_CategoryID": 1,
      "Supplier_SupplierID": 1,
      "UnitsInStock": 39,
      "UnitsOnOrder": 0,
      "ReorderLevel": 10,
      "Discontinued": false
    }
  ]
}

This is due to the in-process based connectivity available in the single CAP server process.

Let's stop the CAP server at this point.

Mock the remote service in a separate process

In a second terminal window, let's now start the standalone mocking of the required northbreeze service with the cds mock command³, like this:

cds mock northbreeze

We should see output like this:

[cds] - using bindings from: { registry: '~/.cds-services.json' }
[cds] - connect to db > sqlite { database: ':memory:' }
  > init from srv/external/data/northbreeze.Products.json
  > init from srv/external/data/northbreeze.Categories.csv
/> successfully deployed to in-memory database.

[cds] - mocking northbreeze {
  at: [ '/odata/v4/northbreeze' ],
  decl: 'srv/external/northbreeze.csn:170'
}
[cds] - server listening on { url: 'http://localhost:42623' }

The initial data is loaded as before, the northbreeze service is served, but crucially:

the provided Main service is not served (as we haven't asked it to be)
the required northbreeze service is available on a non-standard (in fact random) port 42623

We can successfully request resources in this mocked remote service at http://localhost:42623/odata/v4/northbreeze.

Start a normal CAP server process to have the local service served

Now in the first terminal window, let's restart the CAP server with cds watch, and we should now see:

[cds] - using bindings from: { registry: '~/.cds-services.json' }
[cds] - connect to db > sqlite { url: ':memory:' }
/> successfully deployed to in-memory database.

[cds] - serving Main {
  at: [ '/odata/v4/main' ],
  decl: 'srv/main.cds:3'
}
[cds] - server listening on { url: 'http://localhost:4004' }

Now, there's no initial data loaded, because that belongs to the required remote northbreeze service and thus not relevant here, because only the Main service is being served.

Why is only the provided Main service being served, and not the required remote northbreeze service, like before?

Get to know the binding registry

To answer that question, we need to recall that highlighted part of the help for the mocking option to cds serve earlier:

It starts in-process mock services for all required services configured in package.json#cds.requires, which don't have external bindings in the current process environment.

Here, in our local-first development context, our "current process environment" is effectively any (and all) CAP server process(es) running locally.

You might have noticed this line appearing in previous CAP server output samples in this post:

[cds] - using bindings from: { registry: '~/.cds-services.json' }

As they start up and shut down, local CAP server processes read and write to this registry file ~/.cds-services.json. They read it to see what services are available (that they might be requiring), and write to it to record the services they're providing (for other locally running CAP server processes).

When we started the separate CAP server to mock the northbreeze remote service with cds mock northbreeze, information was written to this file, recording the fact that this northbreeze service is "provided":

{
  "cds": {
    "provides": {
      "northbreeze": {
        "endpoints": {
          "odata": "/odata/v4/northbreeze"
        },
        "server": 17250
      }
    },
    "servers": {
      "17250": {
        "root": "file:///work/gh/github.com/qmacro/cap-nodejs-local-first-development/remoteservice",
        "url": "http://localhost:42623"
      }
    }
  }
}

As we can see, it also records where the provision is, in this case at http://localhost:42623, which is at the port that the mock server is listening on.

This is why a random port is not such a problem here.

Retry the local to remote proxy - part 1

Now that we have two CAP server processes running, one mocking the required remote service northbreeze, and the other serving the local service Main, let's retry that same request (to get the product data from the mocked remote service, proxied through the local service definition):

curl --url 'localhost:4004/odata/v4/main/Products?$top=1'

Oh dear:

{
  "error": {
    "message": "Entity \"Main.Products\" is annotated with \"@cds.persistence.skip\" and cannot be served generically.",
    "code": "501",
    "@Common.numericSeverity": 4
  }
}

The in-process connectivity available (provided for convenience) cannot be used here, and we have to implement some basic query and connectivity logic which is exactly what we will have to do in a productive scenario anyway.

So let's do that, using the simplest thing that could possibly work - adding this to a corresponding srv/main.js file:

const cds = require('@sap/cds')
module.exports = cds.service.impl(async function() {
  const northbreeze = await cds.connect.to('northbreeze')
  this.on('READ', 'Products', async (req) => {
    return await northbreeze.run(req.query)
  })
})

When a query arrives to read Products data, send it across to northbreeze and pass back whatever is returned.

Once the CAP server in the first terminal window restarts because of this change, note that there's a new log line in the output:

[cds] - connect to northbreeze > odata { url: 'http://localhost:42623/odata/v4/northbreeze' }

This is a direct result of the await cds.connect.to('northbreeze') line above.

Retry the local to remote proxy - part 2

With this simple implementation in place, retrying that same request again will result in some very satisfying log output in both CAP server processes.

Before we do, stop the CAP server in the first terminal window and restart it specifying DEBUG=remote like this, to get more log output detail for remote related activities:

DEBUG=remote cds watch

Now, after retrying the request for a final time, we see this log output in the first (Main) CAP server log output:

[remote] - GET http://localhost:42623/odata/v4/northbreeze/Products?$select=ProductID,ProductName,QuantityPerUnit,UnitPrice,Category_CategoryID,Supplier_SupplierID,UnitsInStock,UnitsOnOrder,ReorderLevel,Discontinued&$top=1 {
  headers: {
    accept: 'application/json,text/plain',
    'x-correlation-id': 'ff4da315-ec6e-4e89-97d4-85f96b270ed6',
    'x-correlationid': 'ff4da315-ec6e-4e89-97d4-85f96b270ed6'
  }
}
[remote] - Executing via native fetch.

We can see that there's an HTTP request, specifically an OData QUERY operation, that's been constructed and sent to the URL where the remote service is being provided⁴.

And in the CAP server process in the second terminal window, where we're separately mocking the northbreeze remote service on 42623, we see that OData QUERY operation arrive:

[odata] - GET /odata/v4/northbreeze/Products {
  '$select': 'ProductID,ProductName,QuantityPerUnit,UnitPrice,Category_CategoryID,Supplier_SupplierID,UnitsInStock,UnitsOnOrder,ReorderLevel,Discontinued',
  '$top': '1'
}

A true inter-process remote service call. All running locally, and orchestrated in the simplest way possible.

Wrapping up

This post has just scratched the surface of what's possible when it comes to working in local-first development mode, with remote services. For more information and stuff that you can practise yourself, we have the CAP Service Integration CodeJam exercises publicly available for you. Happy learning!

Footnotes

"odd" is short for OData Deep Dive, and the service is used in the corresponding SAP Tutorial Navigator mission that I'm rewriting currently - see OData Deep Dive rewrite in the open for details.
Note that since the CAP Apr 2026 release, the SAP Cloud SDK is no longer mandatory for remote communication in development scenarios.

cds mock servicename is actually just shorthand for

cds serve --mocked servicename --in-memory? --port 0

We can also see, via the "Executing via native fetch" line, that the Node-native Fetch API is in use here now, since Apr 2026.

Local-first dev with CAP Node.js - mocking auth

2026-05-12T00:00:00Z

This post is one of a series on local-first development with CAP Node.js.

The mocked authentication strategy

The Authentication Strategies section of the Node.js Security topic in Capire explains the different strategies available, and the "mocked" strategy comes with pre-defined users that can be used, with their various levels of authorisations, to explore, define and test security-related constructs. This mock user configuration can be modified and extended too, but what comes out of the box is definitely enough to get started.

Working through an example

In this post, we'll work through an example of mocking auth, based on content in the auth/ directory of the talk repository.

Note that what's absent here is any form of auth implementation - all declarations available are automatically enforced by CAP's generic service providers.

The service definition

In srv/main.cds there's a single service defined, with a couple of entities that are simple projections on to the entities in the data model:

using northwind from '../db/schema';

service Main {

  entity Products   as projection on northwind.Products;
  entity Categories as projection on northwind.Categories;

}

Starting a CAP server in local development mode with cds watch shows us that the mocked authentication strategy is in play by default:

[cds] - using auth strategy { kind: 'mocked' }
[cds] - serving Main {
  at: [ '/main' ],
  decl: 'srv/main.cds:4'
}

As we haven't yet addressed any auth requirements in our CDS model, access is currently open to all, as we can see¹:

; curl \
  --include \
  --url 'localhost:4004/main/Products?$top=1'
HTTP/1.1 200 OK
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 105

{
  "@odata.context": "$metadata#BasicProducts",
  "value": [
    {
      "ID": 1,
      "name": "Chai",
      "supplier": "Exotic Liquids"
    }
  ]
}

Examine the pre-defined users and their authorisations

We can take a look at the pre-defined user data that is defined for the mocked authentication strategy, with:

cds env requires.auth.users

which will emit something like this:

{
  alice: { tenant: 't1', roles: [ 'admin' ] },
  bob: { tenant: 't1', roles: [ 'cds.ExtensionDeveloper' ] },
  carol: { tenant: 't1', roles: [ 'admin', 'cds.ExtensionDeveloper' ] },
  dave: { tenant: 't1', roles: [ 'admin' ], features: [] },
  erin: { tenant: 't2', roles: [ 'admin', 'cds.ExtensionDeveloper' ] },
  fred: { tenant: 't2', features: [ 'isbn' ] },
  me: { tenant: 't1', features: [ '*' ] },
  yves: { roles: [ 'internal-user' ] },
  '*': true
}

Restrict the service

Let's annotate the service with some basic role based access control (RBAC) requirements - that of needing to authenticate, via the pseudo-role authenticated-user. We can use the @requires annotation:

using northwind from '../db/schema';

@requires: 'authenticated-user'
service Main {

  ...

}

The same curl request as before now fails with an appropriate HTTP 401 status code:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="Users"
Content-Type: text/plain; charset=utf-8
Content-Length: 12

Unauthorized

Authenticate with a pre-defined user

We can re-try the request with one of the pre-defined users²; because the requirement is just for the pseudo-role authenticated-user, we don't need any particular actual role allocated to the user, we just need to be successfully authenticated (and so identified) in this case:

; curl \
  --user alice: \
  --include \
  --url 'localhost:4004/main/Products?$top=1'
HTTP/1.1 200 OK
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 105

{
  "@odata.context": "$metadata#BasicProducts",
  "value": [
    {
      "ID": 1,
      "name": "Chai",
      "supplier": "Exotic Liquids"
    }
  ]
}

Try some finer-grained access restrictions

With the @restrict we can define finer grained access requirements³ in privilege building blocks of this form:

{ grant:<events>, to:<roles>, where:<filter-condition> }

Let's now add privilege requirements for the Categories entity, like this:

using northwind from '../db/schema';

@requires: 'authenticated-user'
service Main {

  entity Products   as projection on northwind.Products;

  @restrict: [
    {
      grant: 'WRITE',
      to   : 'buyer'
    },
    {
      grant: 'READ',
      to   : 'any'
    }
  ]
  entity Categories as projection on northwind.Categories;
}

This says that any (authenticated) user can read the categories, but only a user with the buyer role can perform "write"-semantic operations.

Confirm read operations are permitted

Let's check that "read"-semantic operations are allowed for authenticated users (remember that the entity access is also governed by the authenticated-user pseudo-role restriction on the service that contains it):

; curl \
  --user alice: \
  --include \
  --url 'localhost:4004/main/Categories?$top=1'
HTTP/1.1 200 OK
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 155

{
  "@odata.context": "$metadata#Categories",
  "value": [
    {
      "CategoryID": 1,
      "CategoryName": "Beverages",
      "Description": "Soft drinks, coffees, teas, beers, and ales"
    }
  ]
}

Looks OK.

Try a write operation

Now for a "write"-semantic operation. Let's go big and try DELETE:

; curl \
  --user alice: \
  --include \
  --request DELETE \
  --url 'localhost:4004/main/Categories/1'
HTTP/1.1 403 Forbidden
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 74

{
  "error": {
    "message": "Forbidden",
    "code": "403",
    "@Common.numericSeverity": 4
  }
}

Alice, with the admin role, is denied.

Give the user more access in the mocked strategy

We can also modify and add to the pre-defined user definitions for the mocked authentication strategy. Let's do that, adding a couple of extra roles for Alice in a separate .cdsrc.json file in the project:

{
  "cds": {
    "requires": {
      "auth": {
        "users": {
          "alice": {
            "roles": [
              "admin",
              "buyer",
              "head-office"
            ]
          }
        }
      }
    }
  }
}

One of the roles is buyer, so let's now retry the previous request:

; curl \
  --user alice: \
  --include \
  --request DELETE \
  --url 'localhost:4004/main/Categories/1'
HTTP/1.1 204 No Content
OData-Version: 4.0

Success!

Wrapping up

With the mocked authentication strategy, we can embrace and work on the important aspect of securing our app or service right from the very start. CAP makes it easy to do the right things here.

For more information, see the Authentication topic in Capire.

Footnotes

The JSON output in these examples has been pretty-printed for readability here.
The --user option for curl allows us to specify a username and password separated by a colon, so alice: here is just the username combined with an empty password (there are no passwords for these users). If we'd just specified --user alice without a colon, then curl would have prompted us for a password - we could have then just pressed Enter but this is one step we can avoid.
In fact, @requires is just a convenience shortcut for @restrict. The annotation
```
@requires: 'authenticated-user'
```
that we used earlier is equivalent to
```
@restrict: [ { grant: '*', to: 'authenticated-user' } ]
```

DJ Adams

Knowledge and netiquette in today's AI era

Knowledge engineering and lifecycle management

Netiquette and how our connections are changing

Timeless principles, agnostic design and the power of CAP's abstractions

The wonder of cds.service.bindings

Exploring the first two circles

Start monitoring the local service binding registry

Create a simple CAP project A

Check the local service binding registry

Connect and consume CatalogService locally

Consume the provided service from elsewhere

Fetch the service bindings

Connect to the service

Send a query to the service

Wrapping up

Footnotes

reCAP 2026 talk resources

Expressions

Abstractions

Computing memories

Blogging in en-GB

CAP service authentication at design time and in production

Default auth settings for development

Default auth settings for production

Understanding the mechanism

Wrapping up

Book Overflow and two architectural patterns in CAP

Ports and adapters

Transactional outbox

Further reading

Local-first dev with CAP Node.js - mocking messaging

Everything is an event

Working through an example

The containing project definition

Examining the emitter

The emitter service definition

The emitter service implementation

Messaging configuration

Examining the receiver

The receiver implementation

Trying it out

Starting up the emitter

Invoking the greet action

Looking at the message queue

Starting up the receiver

Wrapping up

Local-first dev with CAP Node.js - mocking remote services

Calesi and mocking remote services

Working through an example

Examining and importing the candidate remote service

Mocking is automatically and immediately initiated

The package.json file is extended

Reviewing the situation

Add data for the mocked remote service

Have some data generated

Retrieve data and use that too

Move the data closer to the service

Switching to a more realistic scenario

Set up a local to remote proxy definition

Examine the CAP server logs now

Mock the remote service in a separate process

Start a normal CAP server process to have the local service served

Get to know the binding registry

Retry the local to remote proxy - part 1

Retry the local to remote proxy - part 2

Wrapping up

Footnotes

Local-first dev with CAP Node.js - mocking auth

The mocked authentication strategy

Working through an example

The service definition

Examine the pre-defined users and their authorisations

Restrict the service

Authenticate with a pre-defined user

Try some finer-grained access restrictions

Confirm read operations are permitted

Try a write operation

Give the user more access in the mocked strategy

Wrapping up