DEV Community: Frédéric Barthelet

Definitely a must read for anyone designing CLI for the agent era!

Frédéric Barthelet — Wed, 15 Apr 2026 11:31:18 +0000

Julien Vallini for Alpic

Apr 15

Designing a CLI for Both Humans and Agents

#cli #ai #devtools #opensource

Comments 1

5 min read

Better MCP tools/call Error Responses: Help Your AI Recover Gracefully

Frédéric Barthelet — Mon, 28 Jul 2025 07:41:02 +0000

When building MCP servers, we often focus on the happy path: what happens when tools execute successfully. But what about when things go wrong? The quality of your error responses can make the difference between a frustrated user and an AI that recovers gracefully on its own.

Understanding MCP Error Types: Protocol vs Tool Errors

Before diving into error response strategies, it's crucial to understand the distinction between two types of errors in MCP:

MCP Protocol-Level Errors

These are errors in the MCP communication itself:

Connection closed or request timeout
Tool not found
Malformed requests or protocol violations
Internal server errors

These errors trigger standard JSON-RPC error responses and typically indicate something is fundamentally broken with the request or the server.

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Request Timeout"
  }
}

Tools/call Errors (The Focus of This Article)

These are errors that occur during tool execution. The tool was found and called, but something went wrong during the processing. These should not be returned as MCP protocol errors, but as successful MCP JSON-RPC responses with isError: true in the result payload.

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "An error occurred."
      }
    ],
    "isError": true
  }
}

Tools/call Error Responses Are Context, Not Dead Ends

Why bother sharing so many details about the difference between these two error formats? They're both still errors, right? Nothing that needs much attention.

Wrong! MCP protocol-level errors are captured by the MCP client, eventually surfaced in the UI (like a notification in Claude), and discarded. On the other hand, tools/call errors are injected back into the LLM context window, just like successful responses. Smart error messages can be leveraged by the model as much as any other prompt, giving it a chance to recover from the error without human intervention.

Most open-source MCP implementations I've seen return generic tool error messages that leave the AI (and users) in the dark. Let's look at what it takes to rework error messages and increase your server's overall quality.

3 Use-Cases of Better Error Responses

Here are examples of elevated error messages that improve model task completion rate (the north star metric used to evaluate MCP server quality).

Tool Ordering Guidance

If the application's state prevents the model from using a tool for a given resource, provide instructions on how to update that state to make the tool usable. For example, if you're a famous three-letter infrastructure company exposing a tool to terminate an instance, but this tool can only be called when the instance is in a stopped state, say so in the error message.

{
  "content": [
    {
      "type": "text",
      "text": "You can't terminate an instance in the running state. Use the stop_instance tool first on this instance."
    }
  ],
  "isError": true
}

Refined Validation Messages

When tool input validation criteria aren't fully representable in JSON schema, use tool error messages to give the model additional context. If you're a travel company exposing a booking tool on your MCP server and the model accidentally misinterprets the current year for your booking request, you can correct it:

{
  "content": [
    {
      "type": "text",
      "text": "The requested travel date cannot be set in the past. You requested travel on July 31st, 2024, but the current date is July 25th, 2025. Did you mean to plan for travel on July 31st, 2025 instead?"
    }
  ],
  "isError": true
}

Smart Unknown Error Handling

Even when you can't provide precise details about an error, give the model instructions on retry strategy and fallback actions to direct the user to:

{
  "content": [
    {
      "type": "text",
      "text": "An unknown error happened. Try again immediately. If it's the 3rd time you're encountering this issue, provide the user with a link to https://mydashboard.example.com/manual-task to perform the task manually."
    }
  ],
  "isError": true
}

Conclusion

Error handling in MCP isn't just about graceful failures—it's about creating collaborative experiences where AI can self-correct and recover. By treating error responses as contextual guidance rather than terminal states, you transform frustrating dead ends into stepping stones toward success.

Remember: every error response is an opportunity to teach the AI how to do better next time.

What patterns have you found effective for MCP error handling? Share your experiences in the comments below.

9 Surprises using AWS EventBridge Scheduler

Frédéric Barthelet — Thu, 01 Dec 2022 17:56:30 +0000

AWS released its news AWS EventBridge Scheduler service, dedicated to planing tasks in your application. The service is available on all regions using the SDK, the CDK, the CLI and the web management console.

Since the service was released, I've been thoroughly migrating existing workloads that leveraged homemade scheduling features using DynamoDB TTL or any other contraption. This article serves as a discovery report, describing the good, the bad and my general recommendations when it comes to using this new serverless scheduling managed service, in an effort to save someone else troubles understanding the use cases and limits of the service.

What is the Scheduler

The Scheduler is an AWS managed service, dedicated to scheduling one-time or recurring triggers targeting AWS services actions.

There are 3 types of schedules:

One-time schedules - December 21st at 7AM UTC
Rate-based schedules, allowing recurring tasks using frequency rate - every 2 hours
Cron-based schedules, allowing recurring tasks using a cron expression - every Friday at 4PM

Schedules can be grouped in Schedule Groups. Both Schedules and Schedule Groups can be provisioned using a CRUD API on the service.

Rate-based and cron-based schedules can be triggered in a specific timeframe using a start date and an end date. One-time and cron-based schedules are sensible to an optional timezone parameter in which the schedule expression should be evaluated.

Each schedule can trigger one target. There are 3 types of targets:

Templated Isomorphic targets
Templated Service-specific targets
Universal targets

Unlike Universal targets that require the Scheduler to bootstrap an execution environment to use the AWS SDK, both Templated Isomorphic and Service-specific targets are most likely leveraging EventBridge API Destination features to interact with the destination AWS services using their HTTP interface.

Templated Isomorphic targets

You can trigger the following services APIs using the same generic target definition at the creation of your schedule:

The target definition only requires an arn (like the one of the Lambda function to be invoked or the Step Functions state machine to be started). It allows the use of an optional input field.

Templated Service-specific targets

You can trigger the following services APIs using additional service-specific options at the creation of your schedule:

Like for templated isomorphic targets, the schedule definition only requires an arn. In addition to the optional input field, one service specific attribute can be added, named ${service}Parameters to the schedule target definition in order to further configure the action. For exemple, you can provide a SqsParameters parameter in order to specify MessageGroupId value for the SQS SendMessage target.

Universal targets

Universal targets allows schedules to target any AWS service and any corresponding action using an abstracted compute environment with the SDK capabilities. Universal target are defined using the magic string arn:aws:scheduler:::aws-sdk:${service}:${apiAction} as an arn. This feature is similar to the AWS Step Functions SDK services integration released in September 2021.

The good surprises 🎉

The Scheduler is right on time !

It's not clearly written in the documentation, but Marcia Villalba release post mentions a granularity of one-minute. We can safely assume schedules precision is within a 60 seconds margin when flexible time window is disabled. In practice, running tests over 10.000 data points, using both Universal and Templated Targets aiming at invoking the same Lambda function, the results show both modes successfully trigger within 50 seconds.

In addition, delta between scheduled time and invocation time has a roughly unified repartition from 0 to 50 seconds

Being right on time with a precision of a minute is a huge step forward compared to the 48 hours guarantee on DynamoDB TTL expiration. Of course this DynamoDB garbage collection feature was never intended for precise scheduling, but measured results were encouraging and a lot of application still relied on this mechanism. Lately, delta has considerably increased and the Scheduler release felt like a blessing!

If you require a scheduling mechanism with a precision to the exact second, have a look at the CDK Scheduler.

Authorization has a per-Schedule granularity

The EventBridge Scheduler allows use of a different role for each Schedule, similar to EventBridge Rules current behavior. Granularity with minimal policy documents is therefore easily enforceable and misconfiguration can be avoided thanks to thorough permission management.

This Schedule specific role should include permissions for the targeted service and its corresponding action. This role should also be assumable by the Scheduler service.

Since one-time Schedule will mostly be provisioned at runtime (like for instance to send a reminder email to a user 10 days after its initial connection), please note that the role assumed by the compute unit in charge of creating the Schedule should:

allow schedule:CreateSchedule action
allow iam:PassRole action for the role to be used by the Schedule

Schedules access patterns are relevant

Schedules can be grouped in Schedule Groups (they are by default created in a group conveniently named default). Schedule ARNs are predictable, no technical IDs are involved in the management of Schedules and Schedule Groups. A Schedule ARN follows this syntax: arn:aws:scheduler:${region}:${accountId}:schedule/${scheduleGroupName}/${scheduleName}.

Listing existing Schedules with the ListSchedule action allows multiple access pattern:

list all Schedules
list all Schedules in a specific Schedule Group
list all Schedules whose name has a specific prefix
list all Schedules in a specific Schedule Group and whose name has a specific prefix

This allow for clear business logic separation like in multi-tenant applications, ensuring no collision occurs within code when it comes to handling Schedules dedicated to a single tenant. It is strangely resembling a composite primary key access pattern on a DynamoDB Table, where Schedule Group names officiate as separate partitions and Schedules as distinct items who's name is the sort key.

Get, Update and Delete actions require however an exact identifier - Name and GroupName (which is equivalent to providing the ARN).

Scheduler is protected against recursive calls

Universal targets leverage a dedicated compute unit to execute SDK actions for a specific Schedule. Not all SDK services and actions are included in this environment. For instance, all actions of the Scheduler are excluded, preventing unintended recursive calls that may break the bank! I did however had a lot of fun trying to create a recursive Schedule targeting arn:aws:scheduler:::aws-sdk:schedule:createSchedule with the same payload.

The not so good surprises 🤯

Schedules remain visible after their job is done

The Scheduler does not distinguish still-relevant and irrelevant Schedules. What I call irrelevant Schedules are:

one-time Schedules who's scheduled date has passed and target was successfully invoked
recurring Schedules who's end date has passed and target was successfully invoked on all occurrences
deactivated Schedules. Those are the only irrelevant Schedules that can be identified and filtered out of listing operations

Those Schedules are indeed irrelevant since there is no remaining tasks associated with them. Except for debugging purpose, they have no remaining impact on the overall application behavior.

Keeping those irrelevant Schedules around induces various problems.

Irrelevant Schedules count towards the per region quota of 1 million Schedules. While this quota can be increased, any limitation impacting an application history (formerly, all Schedules that were ever created in the context of a specific application) is doomed to be a critical problem at some point. Remember disk space storage issues induced by endlessly writing application logs? We're finding ourself in the exact same situation here.

In addition, no validation occurs at Schedule creation to ensure newly created ones are not already irrelevant at the time of creation.

Finally, there is no efficient way to list remaining relevant Schedules at any time on a given workload.

Templated Targets `input` field mapping is highly inconsistent

The optional input field that you can use on templated targets is highly inconsistent. I had to experiment quite a lot with schedules to be able to produce the following few mappings with API reference documentation:

EventBridge – PutEvents input will be mapped to Entries[0].Detail field
Kinesis Data Firehose – PutRecord -> input will be mapped Record.Data field
Lambda – Invoke -> input will be mapped to Payload field
Amazon SNS – Publish input will be mapped to Message field
Amazon SQS – SendMessage input will be mapped to MessageBody field
Step Functions – StartExecution input will be mapped to input field

The Scheduler supported action list is inconsistent

Actions relative to Schedules are referenced with schedule:${action}, while actions relative to Schedule Groups are referenced with scheduler:${action} in policy documents. Small detail here, but can be really troublesome the first time you write a policy document to use for the Scheduler. You can have a full list of all actions in the Scheduler documentation.

Update action has a replace all strategy

Missing optional fields in an update statement are replaced with their default value. Updates on Schedules has unintended behavior if any value that should remain unchanged are not provided in the payload.

Prefix attribute for ListSchedule action regex does not match name attribute regex

Schedule name has the following regexp: ^[0-9a-zA-Z-_.]+$
Listing Schedules using a name prefix filter only accepts an argument following this regexp: ^[a-zA-Z][0-9a-zA-Z-_]*$

Long story short: you can only use name prefix filter access pattern for Schedules who's name starts with an alphabetical character. I initially designed my one-time Schedules name to start with ISO8601 representation of the scheduled date to circumvent irrelevant Schedules issue. This proved to be a wrong design intent since all ISO8601 representations start with a number, and cannot therefore be used as prefix attribute in a ListSchedule operation.

Should you use the AWS EventBridge Scheduler?

You're currently using CloudWatch Rules or EventBridge Rules

Rules using cron-based and rate-based schedules should be migrated to EventBridge Scheduler. You'll be able to reach more target types than with existing EventBridge target catalog. You'll also be able to remove a few Lambda functions who's sole purpose was to use the SDK to reach a service not integrated with EventBridge. Finally, the Scheduler has 14 million Schedules included in its free tier each month, your application may not use as much and you'll remain free of charge after migrating to this new service.

You're currently using DynamoDB TTL

Using DynamoDB TTL to schedule one-time tasks can now be definitely deprecated. The pricing impact of removing DynamoDB and Lambda altogether from the required infrastructure to implement such scheduling mechanism is worth it. Even if you're currently fine with the 48 hours window of DynamoDB TTL, you should rely on the Scheduler with the corresponding flexible time window parameter.

Key take-aways

Always use Universal Targets

Indeed, universal targets have quite a few advantages:

📚 Targets catalog All templated targets can be achieved with universal targets. Universal targets cover almost all AWS services and actions.
👨‍💻 Developer Experience You can safely rely on targeted service actions documentation instead of hoping you're aiming for the correct field using input shortcut provided by templated targets. Your schedule definition will be consistent and self-explanatory since they won't be relying on EventBridge Scheduler specific shorthand syntax.
⚙️ Configurability You can use all allowed configuration options for the action you want to trigger.
💶 Cost There is no additional charges to use universal targets, it costs the same while doing much more!
🏃 Schedule precision Unlike what I initially assumed, universal targets are slightly closer to the requested scheduled time (considering p90 delta).

Provision at the right time

Schedules and Schedule Groups can be created at deploy time, using any IaC framework, or at runtime, using the SDK. A few recommendations regarding when to provision which:

Almost always, Schedule Groups should be provision at deploy time.
Schedule Groups used for tenancy segregation in multi-tenant applications are the only groups that should be provisioned at runtime, at the time of tenant creation.
Recurring Schedules without start and end dates are relevant throughout the entire lifespan of an application, they should be provisioned using IaC at deploy time.
One-time Schedules and recurring Schedules with a given timeframe should be created at runtime, resulting from a user action, within their respective previously provisioned Schedule Groups

If you need to use UpdateSchedule actions, always use GetSchedule beforehand as starting point for your command payload

Indeed, update actions in EventBridge Scheduler use a replace all attributes strategy. If you omit a value that was previously given (at creation or previous update), the Schedule will use the default value for the corresponding missing attributes. This can lead to unexpected behavior.

Prefer the use of UTC

Timezone management is a pain, always. The Scheduler tries to compensate with an optional timezone parameter and implements daylight savings time shift.

In most cases, if you want to avoid timezone strange behavior, prefer relying on a date management library to convert one-time Schedules scheduled time in UTC before creating it.

Cron-based Schedules are the only relevant Schedules that might benefit from timezone sensitive settings.

Rate-based Schedules are unaffected by this setting.

Always use a DLQ on your Schedules

If it can fail, it will fail at some point. CloudWatch metrics available for the Scheduler cannot distinguished failed target invocation on a per-Schedule basis. Provisioning a dead-letter queue and referencing it as destination for all your schedules is a must have!

Implement a regular cleanup process for irrelevant Schedules

Regular cleaning of now irrelevant Schedules should be implemented to keep the total number of Schedules under control and avoid reaching the 1 million quota for the service. You can rely on a rate-based Schedule to regularly invoke a Lambda function dedicated to listing and deleting irrelevant Schedules. You can adjust the retention period, for debugging purpose, for which you still want to keep a Schedule around by changing your programmatic filtering parameters.

Conclusion

All things considered, the new AWS EventBridge Scheduler service feels like a blessing, especially for one-time Schedules where there were no robust alternatives on AWS. Google Cloud Platform had Cloud Task since 2018 for this specific purpose. It's nice to see AWS matching the offer and providing, almost for free, a dedicated managed service with precise scheduling mechanism.

At the time of publishing this discovery report, some questions remain unanswered. Among the various subjects I'll dig into, but save the findings for a separate article, you'll find:

why and when to use the flexible time window parameter
why and when to use the client token. How can you ensure idempotency when you interact with the Scheduler
what kind of L2/L3 CDK Construct can and should be implemented to ease up integration of this service

Serverless Framework ️<3 AWS CDK

Frédéric Barthelet — Wed, 26 Jan 2022 10:25:21 +0000

There are plenty of articles out there comparing major Infrastructure as Code frameworks when it comes to building and deploying an AWS serverless stack. A serverless newcomer can easily be overwhelmed by the wide variety of solutions available: Serverless Framework, AWS CDK, Pulumi, Terraform, SST, Architect...
Rather than pitting those solutions against each other, this article focus on leveraging two of them, Serverless Framework and AWS CDK, for what they are best at and making them work together seamlessly.

This solution does not require any additional dependency, plugin or CLI tool. It works right out of the box, using native CDK API and Serverless Framework service definition properties.

TL;DR

The following service file definition provides a simple way to deploy an application relying on Lamba-centric resources as well as other type of resources, leveraging respectively Serverless Framework and CDK, all using a single CloudFormation deployment. This solution improves greatly the developer experience by:

leveraging the simple configuration format of the Serverless Framework
leveraging AWS CDK constructs rather than vanilla CloudFormation for resources outside of the scope of the Serverless Framework
using a single language to define the entire stack

// serverless.ts

import type { AWS } from '@serverless/typescript';
import { App, DefaultStackSynthesizer, Stack } from 'aws-cdk-lib';
import { AttributeType, Table } from 'aws-cdk-lib/aws-dynamodb';

const app = new App();
const stack = new Stack(app, undefined, {
  // Override default synthetizer to prevent check related to CDK bootstrap
  synthesizer: new DefaultStackSynthesizer({
    generateBootstrapVersionRule: false,
  })
});

const table = new Table(stack, 'MyDynamoDBTable', {
  partitionKey: { name: 'PK', type: AttributeType.STRING }
});

const serverlessConfiguration: AWS = {
  service: 'serverless-framework-loves-aws-cdk',
  provider: {
    name: 'aws',
    runtime: 'nodejs14.x',
    iam: {
      role: {
        statements: [
          {
            Effect: 'Allow',
            Action: [ 'dynamodb:PutItem' ],
            Resource: [ stack.resolve(table.tableArn) ]
          }
        ]
      }
    }
  },
  functions: {
    saveUser: {
      handler: 'saveUser.main',
      environment: {
        TABLE_NAME: stack.resolve(table.tableName)
      },
      events: [
        { http: 'POST /user' }
      ]
    }
  },
  package: { individually: true },
  resources: app.synth().getStackByName(stack.stackName).template
};

module.exports = serverlessConfiguration;

How does it actually work?

Let's deep dive, step by step, in this service file, and understand how Serverless Framework and AWS CDK work together seamlessly at provisioning a state of the art serverless application.

Serverless Framework TypeScript service file

Since v1.72.0, the Serverless framework accepts serverless.ts as a valid service file in addition to the more commonly-known serverless.yml, serverless.json and serverless.js file formats. Using serverless.js or serverless.ts service definition is a requirement to implement this solution. Both those formats allow programmatic execution using Node.js in order to build the output service definition. In addition, you benefit from TypeScript definitions exported by @serverless/typescript package to help you build your Serverless Framework service definition properly.

// serverless.ts

import type { AWS } from '@serverless/typescript';

const serverlessConfiguration: AWS = {
  service: 'serverless-framework-loves-aws-cdk',
  provider: {
    name: 'aws',
    runtime: 'nodejs14.x'
  }
};

module.exports = serverlessConfiguration;

AWS CDK pure resources

Within the same serverless.ts file, or in any other file, you can bootstrap your CDK application, creating a new App and Stack. You can then start to add resources not natively handled by the Serverless Framework, based on your app's requirements, referencing the newly created stack as the resource scope.

import { App, Stack } from 'aws-cdk-lib';
import { AttributeType, Table } from 'aws-cdk-lib/aws-dynamodb';

const app = new App();
const stack = new Stack(this.app, undefined, {
  // Override default synthetizer to prevent check related to CDK bootstrap
  synthesizer: new DefaultStackSynthesizer({
    generateBootstrapVersionRule: false,
  });

const table = new Table(stack, 'MyDynamoDBTable', {
  partitionKey: { name: 'PK', type: AttributeType.STRING }
});

Shipping AWS CDK resources within Serverless Framework generated CloudFormation

In order to bridge AWS CDK and Serverless Framework, you can use native features from both frameworks.

On one side, Serverless Framework provides an option to include custom CloudFormation, using the resources property from the service definition. This property is usually used to inject vanilla CloudFormation, but we'll leverage AWS CDK to avoid doing so.

On the other, AWS CDK provides an API to programmatically generate a Cloud Assembly using the synth method of any App instance. A Cloud Assembly instance is a CDK internal class used to represent a deployable cloud application. Each CDK App can contain multiple CDK Stack, but once again, the CDK provides an API to select a specific stack representation from a Cloud Assembly instance. Finally, each stack of a Cloud Assembly instance exposes the underlying CloudFormation template, as generated by AWS CDK CLI operations.

Using AWS CDK API to generate desired template, and injecting it within Serverless Framework service definition resources property does the trick bridging both frameworks.

const serverlessConfiguration: AWS = {
  // ...
  resources: app.synth().getStackByName(stack.stackName).template
};

Adding references to AWS CDK resources within Serverless Framework service definition

There's no good bridging both frameworks if they can't interact with each other. Serverless Framework Lambda handlers usually need resource specific identifiers in order to interact with those resources.

Exporting CDK-generated DynamoDB table name to Serverless function

In order to insert new items within AWS CDK provisioned DynamoDB table, let's create a new function using Serverless Framework service definition. This function will implement AWS SDK @aws-sdk/lib-dynamodb to execute a PutItem command. This method requires the DynamoDB table name in order to insert the new item in the correct table. One way to pass the variable representing the DynamoDB table name is to use the environment property of the function definition.

const serverlessConfiguration: AWS = {
  // ...
  functions: {
    saveUser: {
      handler: 'saveUser.main',
      environment: {
        TABLE_NAME: 'Injecting DynamoDB table name here'
      },
      events: [
        { http: 'POST /user' }
      ]
    }
  },
};

The actual value for the DynamoDB table, provisioned using AWS CDK, is not known before deployment. One could solve this using tableName props from CDK Table construct, however it is good practice NOT constraining its name value as conflict may occur if two tables share the same name within the same AWS account and region (which will happen if you deploy the same Serverless service twice with different stage value). This goes for many resources where unicity constraints are imposed within the same AWS account, or even globally (like S3 bucket name)!

In order to resolve at deployment the actual table name, one can use CloudFormation intrinsic functions. In the case of a DynamoDB table name, the Ref intrinsic functions will do the trick following DynamoDB CloudFormation documentation. With AWS CDK, there is no need to bother with intrinsic function syntax. Each construct exposes a set of property representing the resource return values, that will ultimately resolves to intrinsic functions under the hood. For DynamoDB Table construct, table.tableName resolves to the actual table name.

TABLE_NAME: table.tableName

The above statement will however translate to a completely unexpected value in the generated CloudFormation template:

TABLE_NAME: ${Token[TOKEN.183]}

AWS CDK actually resolves some value at a later stage of the app's lifecycle and uses tokens as placeholder in the meantime. In order to get the underlying value behind this CDK generated token, we can use resolve method from the CDK Stack:

TABLE_NAME: stack.resolve(table.tableName)

This completes proper setup of the Serverless Framework function in order to perform operations with the CDK generated DynamoDB table.

const serverlessConfiguration: AWS = {
  // ...
  functions: {
    saveUser: {
      handler: 'saveUser.main',
      environment: {
        TABLE_NAME: stack.resolve(table.tableName)
      },
      events: [
        { http: 'POST /user' }
      ]
    }
  },
};

Granting Serverless function permissions to interact with CDK-generated DynamoDB table

Similarly, Serverless Framework service definition will require additional configuration to ensure the saveUser function is actually allowed to insert new items in the DynamoDB table.

This is usually done using the provider.iam.role.statements configuration, adding a new IAM Policy statement which allows DynamoDB PutItem operation.

const serverlessConfiguration: AWS = {
  // ...
  provider: {
    iam: {
      role: {
        statements: [
          {
            Effect: 'Allow',
            Action: [ 'dynamodb:PutItem' ],
            Resource: *,
          }
        ]
      }
    }
  }
};

While opening up IAM Policy statement effect to all DynamoDB table is tempting and very easy to implement, it is not recommended, is considered a way too broad permission and may raise security concerns.

You can however overcome this issue following the same principal than before: CDK Table construct exposes a tableArn property than can be used to narrow down resources with whom PutItem is actually permitted.

Resource: stack.resolve(table.tableArn)

Limitations

Using synth API from AWS CDK to access the underlying Cloud Assembly instance and its CloudFormation template has its limits: no asset can be uploaded on AWS as part of the normal deployment cycle of AWS CDK. AWS CDK relies on a bootstrapping separate stack, that needs to be provisioned independently, whenever one of the resource leverages CDK Assets. For example, deploying Function constructs as part of your CDK stack requires file and/or Docker images to be uploaded to your AWS account, and therefore requires the bootstrapping stack to perform such upload.

Using AWS CDK to complement the Serverless Framework often mean that you won't actually ever rely on Function construct, Lambda provisioning being Serverless Framework scope, but it's worth mentioning as a limitation in case another resource type, not handled by Serverless Framework, also relies on assets being uploaded.

Conclusion

This code snippet and detailed explanations is of course only demonstration of what can be achieved using both Serverless Framework and AWS CDK to deploy a serverless application, using best of both worlds to improve consequently the overall developer experience.

I strongly advise to structure and split your CDK resources in a dedicated project directory, in order to keep serverless.ts as minimal as possible and to implement CDK recommendations in terms of construct architecture.

Serverless can benefit from not being so Lambda-centric

Frédéric Barthelet — Wed, 12 Jan 2022 12:59:30 +0000

Stop writing unnecessary code

As a developer, I need to write code to develop specific features for a project. However, each line that I write is a potential futur bug and increases my project technical debt.

Less code is better. Serverless services have ways to enable you to remove more code than traditional architectures. The use of managed services reduces the amount of boiler plate code that does not directly adds value to your application while retaining the possibility to write full custom code where it's needed most.

One can argue that full-fledged frameworks achieve the same result of reducing boilerplate code. However, it requires the development team to continuously update this code dependency to its latest revision and ship frequent dependency updates in production. With managed services, this burden is passed down to the cloud provider.

Most software engineers relates serverless to its per-use ephemeral compute environment - also known as FaaS - (Lambda/ECS for AWS, Cloud Functions for GCP or Azure Functions for Azure), often missing on a large opportunity offered by all the other serverless services a cloud provider has to offer. Serverless real value is not within compute services, but rather in side-car managed services, handling task usually handled by non-ephemeral compute environment.

This article focus on missed opportunities to write less code and leverage managed serverless services, where those can handle efficiently and flawlessly a large number of request without the need to write or depend on a single runtime-executed line of code. I'll dive on a specific exemple, using AWS, to explain the use case and benefits of using non-compute services and actually have them interact in order to develop a specific feature - hereby named functionless.

What you can do with AWS Lambda

Lambda can be invoked from a variety of services, allowing the development of event-driven architectures. With the variety of triggers offered to request the execution of your code, the possibilities are endless. You can easily react to a change in your database, to a new file being upload on your bucket, to a new user being registered on your application.

The versatility of writing your own code and execute it in reaction to those changes is however often in contrast with what I actually see people implementing in their code base.

Countless times I've seen the magic triptych: API Gateway - Lambda - DynamoDB

This triptych is often used to develop HTTP endpoints, be it a simple CRUD REST API used as a backend or an incoming webhook endpoint receiving notifications from 3rd parties.

Why do we see this architecture so often ?

Serverless Framework is lambda-centric and encourages new adopters to trigger lambdas everywhere
Imperative code is familiar to developer, while AWS services configuration is much less common knowledge
The developer experience setting up an alternative architecture not relying on Lambda is considerably worse (you can jump to the end of this article for more information)

Let's take the exemple of writing-reading data to DynamoDB.

What you should do with AWS Lambda

In order to identify precisely what you should do within your Lambda handlers' code, it is important to understand what NOT to do. As with our previous exemple, almost everything can be done directly within API Gateway.

Authorization: using a Cognito user pool or an API key
Input validation: using built-in JSON schema validation configuration
Routing: describing specific routes in API Gateway rather than use a catch all {proxy+} integration
Content transformation: transform HTTP request content and map to the corresponding attributes as expected in the database layer

At the end of the day, for such "simple" operations, you can almost always by-pass lambda altogether and rely on the following functionless architecture.

Why should I opt-out of Lambda for such use cases ?

As I explained at the beginning of this article, writing less code has benefits of its own for a project code base in the long run. However, that's not the only advantages brought by Functionless.

💰 Cost

API Gateway incurred cost in the Functionless architecture are always the same, whether you use it for validation, routing, authorization and content transformation or not.

The cost repartition in the original triptych architecture are as follow (per million executions, in us-east-1 region):

3,50$ for API Gateway
0,70$ for Lambda (including invocation + 30ms warm execution)
1,25$ for DynamoDB

Total: 6,45$ per million executions

Removing Lambda from this architecture simply removes Lambda incurred costs from the bills, without increasing other services respective costs, actually cutting off our costs by 13%.

🚀 Performance

The serverless triptych stack - in green on graph below - and functionless stack - in blue on graph below - performs almost identically. The results shown below represents API Gateway latency (not taking networking latency into account) for both stacks with the same feature: a POST request with a payload containing a single attribute resulting with an item being persisted in DynamoDB.

The serverless triptych stack is much more consistent over time with almost all warm responses latency ranging between 30ms and 40ms.

The functionless stack is less performant most of the time - around 50ms - but much faster on some occasions:

6% of the requests have a latency in the 10ms range
16% in the 20ms range

However, in the event of a cold serverless triptych stack, results are considerably worse.

Lambda's cold start issue

Lambda is fast once it's warm. The first request requiring compute from Lambda service is much slower than the consecutive requests due to cold start issues. Lambda actually requires to provision a dedicated environment to run your code. You can overcome this issue using provisioned Lambda instances, but what's the point of going serverless then? Provisioned instances significantly impacts the overall cost of the stack, making it much less competitive.

In this instance, the serverless triptych stack averages at 600ms latency when Lambda is cold, which is 10x more than the warm latency.

Regarding cost, while init duration is not included in billed duration, the overall cost of the execution is much larger due to a larger amount of time required to process the event. In practice, the average billed duration for cold lambda is 188ms, which represents 3,40$ per million execution. Removing this dependency to Lambda cuts off our costs by 42% in worst case scenario (or best case scenario, depending on the way you look at it) - considering all invocations are cold invocations.

🗜 Throttling

Using a functionless stack removes limitations from Lambda service:
Lambda concurrent execution quota (1000 by default) limits the total quantity of lambda being invoked at some point in time in a single AWS account. While this quota can be increased, not using Lambda removes any worry related to concurrency limits. I'm not saying other services used in the functionless stack aren't limited as well: API Gateway has a 10.000 RPS throttling limit as well as a 5000 requests burst limit, while DynamoDB, in its on-demand provisioned capacity, has a 1000 WCU limit per second. You should pay special attention to those services configuration to handle larger RPS on your application. You just have one less service - Lambda - to worry about in a functionless stack.

How to deploy your first functionless feature ?

Now it's time to address the elephant in the room: developer experience. My first interaction with AWS service direct integrations like API Gateway to DynamoDB was a disaster. I was guided in this experimentation following Andrew Baird's guide on using API Gateway as a proxy to DynamoDB from 2016. If you haven't already face the challenge of correctly configuring such direct integration in API Gateway, I strongly suggest you try following this guide. You lose all benefits from using a more performant and less expensive stack if nobody from your team wants to touch API Gateway functionless configuration with a ten-foot pole.

The process of implementing such functionless stack, as described in Andrew's article, will be used as our experience baseline. Moving forward, I'll detail an alternative that can be used to make the overall experience much more enjoyable and practicable.

Integration Uri

In order to forward HTTP requests made to API Gateway to DynamoDB endpoint, you must setup an AWS service integration. The instructions to setup one using the web console requires knowledge on what to fill in the following fields.

Some of those fields can easily be guessed, like region and action, as they are commonly used in other IaC scenarios (like IAM role statements definition).

Others require factual knowledge: all AWS services, including DynamoDB, expose an HTTP API that is used by AWS CLI, SDK, web console. All routes on those API use POST http verb. While this could make sense for our exemple at hand here, calling PutItem operation, it is much less obvious if what you're trying to do is a GetItem or Query operation and you're familiar with SaaS exposing RESTful APIs.

The service you want to use is another one of those parameter that requires factual knowledge: while using dynamodb for the DynamoDB integration is quite straight forward, some other services are less obvious, such as events instead of eventbridge for an EventBridge integration.

The HTTP method - POST - as well as the service to be used - dynamodb - are used in combinaison with the region to form the resource Uri. While using the web console is a great first step in using direct AWS services integration feature, teams often rely on versioned IaC to provision an application, where such helper is not always available. In order to setup such integration using CloudFormation, you'd need to provision an AWS::ApiGateway::Method resource, which requires you to provide the full integration Uri all by yourself. This Uri is a source of frustration for most developers I worked with as it greatly differs from one service to another. In addition, it requires deep understanding of a 15-lines long documentation in order to build it correctly. The resulting CloudFormation templates ressembles something like this:

MyAPIGatewayMethod:
  Type: AWS::ApiGateway::Method
  Properties:
    Integration:
      IntegrationHttpMethod: POST
      Type: AWS
      Uri:
        Fn::Join:
          - ":"
          - - "arn"
            - Ref: AWS::Partition
            - apigateway:eu-west-1:dynamodb:action/PutItem

Hopefully, the CDK provides a way to benefit back from the web console helper to build such Uri, using the AwsIntegration class you only need to provide region, action, service to achieve the same provisioning.

const putItemIntegration = new apigateway.AwsIntegration({
  service: 'dynamodb',
  action: 'PutItem',
  region: 'eu-west-1'
});

Integration mapping template

Choosing a service and an action for API Gateway to forward request to is the first step at building an AWS service integration. The next step is to transform the payload of the HTTP request made to API Gateway into what the integrated AWS service expects.

This is done using Velocity Template Language. Here after is an exemple of such a template:

{
    "TableName": "MyTable",
    "Item": {
        "PK": {
            "S": "Dog"
        },
        "SK": {
            "S": "$context.requestId"
        },
        "name": {
            "S": "$input.path('$.name')"
        }
    }
}

This template shapes the payload of the DynamoDB action. It includes API Gateway custom method to hydrate SK and name attribute's value:

$context.requestId uses a context variable to generate a unique id for the PutItem action
$input.path('$.name') uses an input variable to retrieve a specific value from the HTTP body of the request made to API Gateway

Relying on VTL is cumbersome: it requires additional knowledge of the syntax and it is not easily testable (some librairies gave it a go like API Gateway Template Tester but are currently unmaintained).

Easier integration with aws-apigateway-integrations CDK construct

One way to improve this is to allow the use of imperative language and tools people are used to in the triptych serverless stack to generate such template. With this goal in mind, I started a CDK Construct library, called aws-apigateway-integrations, aiming at simplifying AWS service integration definition, following @aws-cdk/aws-apigatewayv2-integrations module footsteps.

Using the new constructs shipped with this library, you can rely on familiar AWS SDK v3 DynamoDB Commands interfaces in order to build your VTL, simplifying previous template down to:

import { PutCommandInput } from "@aws-sdk/lib-dynamodb";
import { DynamoDBActions, DynamoDBIntegration } from "aws-apigateway-integrations";

const putItemCommand: Omit<PutCommandInput, "TableName"> = {
  Item: {
    PK: "Dog",
    SK: "$context.requestId",
    name: "$input.path('$.name')"
  }
};
const putItemIntegration = new DynamoDBIntegration({
  action: DynamoDBActions.PutItem,
  command: putItemCommand,
  //...
});

Integration response and method response

Request authorization, validation and transformation is only half of the functionless architecture. Both integration response, handling content transformation from DynamoDB HTTP response and method response, detailing API Gateway response typologies, must be provisioned for the overall architecture to work properly.

Integration response similarly relies on VTL to unmarshall content returned by DynamoDB.

{
  "id": "$input.path('$.Item.SK.S')",
  "name": "$input.path('$.Item.name.S')"
}

Such VTL can easily be generated using DynamoDBIntegration, removing the burden from actually defining it yourself.

What's next in the functionless ecosystem ?

While aws-apigateway-integrations is currently a work in progress, I have great hope such integration would greatly facilitate adoption of functionless patterns by greatly improving the overall developer experience. With this in mind, the current development roadmap for this CDK Constructs library includes:

adding JSON schema generation and configuration for API Gateway validation within DynamoDBIntegration
adding IAM role generation within the scope of the construct to allow API Gateway to execute DynamoDB actions
providing better API to wrap $input variable
implementing other AWS services integration

All feedbacks or even contributions are welcome !

Such implementation opens up a lot of new possibilities: a functionless RESTful API where the only code is configuration-only IaC is not out of reach anymore and can help team achieve cheaper, more robust code base with minimal efforts. Such implementation is currently under discussion within Lift project where your feedbacks on the implementation are highly valued.

DEV Community: Frédéric Barthelet

Definitely a must read for anyone designing CLI for the agent era!

Designing a CLI for Both Humans and Agents

Better MCP tools/call Error Responses: Help Your AI Recover Gracefully

Understanding MCP Error Types: Protocol vs Tool Errors

MCP Protocol-Level Errors

Tools/call Errors (The Focus of This Article)

Tools/call Error Responses Are Context, Not Dead Ends

3 Use-Cases of Better Error Responses

Tool Ordering Guidance

Refined Validation Messages

Smart Unknown Error Handling

Conclusion

9 Surprises using AWS EventBridge Scheduler

What is the Scheduler

Templated Isomorphic targets

Templated Service-specific targets

Universal targets

The good surprises 🎉

The Scheduler is right on time !

Authorization has a per-Schedule granularity

Schedules access patterns are relevant

Scheduler is protected against recursive calls

The not so good surprises 🤯

Schedules remain visible after their job is done

Templated Targets input field mapping is highly inconsistent

The Scheduler supported action list is inconsistent

Update action has a replace all strategy

Prefix attribute for ListSchedule action regex does not match name attribute regex

Should you use the AWS EventBridge Scheduler?

You're currently using CloudWatch Rules or EventBridge Rules

You're currently using DynamoDB TTL

Key take-aways

Always use Universal Targets

Provision at the right time

If you need to use UpdateSchedule actions, always use GetSchedule beforehand as starting point for your command payload

Prefer the use of UTC

Always use a DLQ on your Schedules

Implement a regular cleanup process for irrelevant Schedules

Conclusion

Serverless Framework ️<3 AWS CDK

TL;DR

How does it actually work?

Serverless Framework TypeScript service file

AWS CDK pure resources

Shipping AWS CDK resources within Serverless Framework generated CloudFormation

Adding references to AWS CDK resources within Serverless Framework service definition

Exporting CDK-generated DynamoDB table name to Serverless function

Granting Serverless function permissions to interact with CDK-generated DynamoDB table

Limitations

Conclusion

Serverless can benefit from not being so Lambda-centric

What you can do with AWS Lambda

What you should do with AWS Lambda

Why should I opt-out of Lambda for such use cases ?

💰 Cost

🚀 Performance

Lambda's cold start issue

🗜 Throttling

How to deploy your first functionless feature ?

Integration Uri

Integration mapping template

Easier integration with aws-apigateway-integrations CDK construct

Integration response and method response

What's next in the functionless ecosystem ?

Templated Targets `input` field mapping is highly inconsistent