# The ARX.SDK sample application for Amazon DynamoDB
The samples run inside a small application of their own. Their code refers to these files, which aren't part of the ARX packages: `dbContext` (SampleContext.cs) is what each sample is given, `dbContext.Service` the application's ARX service, and the tables' ids, keys, lookups and display names are declared in the schema catalog below. In your application, declare your own tables the same way and create the service once.
`dbContext.Direct` (SampleContext.Direct.cs and the provider's DirectHelper) is the samples' checking code on the plain driver: it resets the sample database and reads rows back to show them. It isn't part of ARX and isn't how an application uses ARX: leave those lines out of code you copy.
## SampleContext.cs
What every sample is given: the connection string (and the ISample interface the samples implement).
```csharp
namespace ArxSamples.DynamoDb;
/// One documentation sample: a scenario a real application has, shown end to end.
public interface ISample
{
/// The name to run it alone: dotnet run -- <name>.
string Name { get; }
/// One line on what it shows.
string Title { get; }
Task RunAsync(SampleContext dbContext);
}
///
/// What a sample is given. Every sample gets the connection string; the application's service and catalog
/// (SampleContext.Application.cs) and the plain AWS SDK read-back helper (SampleContext.Direct.cs) live in their own
/// files, so a sample needs only the files it uses.
///
public sealed partial class SampleContext
{
public SampleContext(string connectionString)
{
ConnectionString = connectionString;
}
public string ConnectionString { get; }
}
```
## SampleOutput.cs
How the samples print: Step for each scenario, Show for what it did, ShowError for an error caught on purpose.
```csharp
using ARX.SDK;
namespace ArxSamples.DynamoDb;
/// How the samples print: a numbered step for each scenario, then what it did.
public static class SampleOutput
{
/// The start of a scenario: Step("1. By the id Create returned").
public static void Step(string text) => Console.WriteLine($" > {text}");
/// What the scenario did.
public static void Show(string text) => Console.WriteLine($" {text}");
/// An ARX error the scenario caught on purpose.
public static void ShowError(ArxException exception)
=> Console.WriteLine($" caught {exception.GetType().Name}: {exception.Message}");
}
```
## SampleContext.Application.cs
The application's DynamoDB client, model, schema catalog and ARX service, created once and shared by the samples.
```csharp
using Amazon.DynamoDBv2;
using Amazon.Runtime;
using ARX.SDK.DynamoDb.Model;
using ARX.SDK.DynamoDb.Services;
using ARX.SDK.Services;
namespace ArxSamples.DynamoDb;
/// The application's DynamoDB client, model, catalog and ARX service, shared by the samples.
public sealed partial class SampleContext
{
private IAmazonDynamoDB? _client;
private ArxDynamoModel? _model;
private ArxSchemaCatalog? _catalog;
private ArxDynamoDbService? _service;
///
/// The DynamoDB client for the endpoint the connection string names. Credentials come from the AWS SDK's own chain
/// (environment, profile, role), never from code; DynamoDB Local on this machine accepts any, so a local endpoint
/// without credentials in the environment gets placeholder ones.
///
public IAmazonDynamoDB Client => _client ??= CreateClient(ConnectionString);
/// How the entities are laid out (SampleModel.cs).
public ArxDynamoModel Model => _model ??= SampleModel.Build();
/// The ids, lookups and selection sets (SampleModel.cs).
public ArxSchemaCatalog Catalog => _catalog ??= SampleModel.Catalog();
/// One service for the whole application: it holds no connection.
public ArxDynamoDbService Service => _service ??= new ArxDynamoDbService(Client, Model, Catalog);
private static IAmazonDynamoDB CreateClient(string endpoint)
{
var config = new AmazonDynamoDBConfig { ServiceURL = endpoint, AuthenticationRegion = Environment.GetEnvironmentVariable("AWS_REGION") ?? "us-east-1" };
var local = Uri.TryCreate(endpoint, UriKind.Absolute, out var uri) && (uri.IsLoopback || uri.Host == "localhost");
return local && Environment.GetEnvironmentVariable("AWS_ACCESS_KEY_ID") == null
? new AmazonDynamoDBClient(new BasicAWSCredentials("local", "local"), config)
: new AmazonDynamoDBClient(config);
}
}
```
## SampleModel.cs
How the application lays out its entities in Amazon DynamoDB, and its schema catalog.
```csharp
using ARX.SDK.DynamoDb.Model;
using ARX.SDK.Services;
namespace ArxSamples.DynamoDb;
///
/// How the application lays out its entities in DynamoDB, in both designs, and its schema catalog.
///
///
///
/// A table per entity: product has a table of its own, keyed by its sku; lead by its
/// email. The entity's attributes are the item's, keys included.
///
///
/// A single table: crm holds customers and their orders together. Each entity's keys are templates:
/// a customer is PK = CUSTOMER#{customer_id}, SK = PROFILE; an order shares its customer's partition,
/// SK = ORDER#{order_number}, so one query reads a customer with its orders. ARX writes the keys, the
/// entity_type attribute that tells the items apart, and the index keys (GSI1: orders by status and date).
///
///
/// Write sharding: events spreads the page views of one page over four partitions (a suffix from a hash of
/// the time), so a popular page doesn't overload one partition; ARX reads them back merged.
///
///
/// The catalog declares each entity's id (supplied: DynamoDB generates none, so ids come from the application),
/// the lookup from an order to its customer, the customer's display name and the order statuses.
///
///
public static class SampleModel
{
public static ArxDynamoModel Build() => ArxDynamoModel.Create()
.Table("product", partitionKey: "sku")
.Table("lead", partitionKey: "email")
.SingleTable("crm", "PK", "SK", crm => crm
.Entity("customer", pk: "CUSTOMER#{customer_id}", sk: "PROFILE")
.Entity("sales_order", pk: "CUSTOMER#{customer_id}", sk: "ORDER#{order_number}")
.Index("GSI1", "GSI1PK", "GSI1SK")
.EntityIndex("sales_order", "GSI1", pk: "STATUS#{status}", sk: "{ordered_on}"))
.SingleTable("events", "PK", "SK", events => events
.Entity("page_view", pk: "PAGE#{page}", sk: "VIEW#{viewed_at}"))
.WriteSharding("page_view", shards: 4, by: "viewed_at")
.Build();
public static ArxSchemaCatalog Catalog() => ArxSchemaCatalog.Create()
.Table("product", ArxIdColumn.Supplied("sku"))
.DisplayName("product", "name")
.Table("lead", ArxIdColumn.Supplied("email"))
.Table("customer", ArxIdColumn.Supplied("customer_id"))
.DisplayName("customer", "name")
.Table("sales_order", ArxIdColumn.Supplied("order_number"))
.Lookup("sales_order", "customer_id", "customer")
.Table("page_view", ArxIdColumn.Supplied("viewed_at"))
.Add("OrderStatus", ArxSelectionSetKind.String, ("OPEN", "Open"), ("SHIPPED", "Shipped"), ("CANCELLED", "Cancelled"))
.Build();
}
```
## SecurityGuard.cs
A security check around ARX calls: suspected injection logged as a security event, strikes, blocking.
```csharp
using ARX.SDK;
namespace ArxSamples.DynamoDb;
/// Where the names (tables, attributes, match columns) in a call come from. It decides what an ARX1017 means.
public enum NameSource
{
/// A name built from what a user sent (a form field, a file header, a query string): ARX1017 is a suspected attack.
UserInput,
/// A name from your code or configuration: ARX1017 is a bug in your code, not an attack. Nobody is blocked.
Code,
}
/// What the guard did with a call.
public enum GuardOutcome
{
/// The call ran.
Done,
/// ARX refused the call with ARX1017; the event is logged and the user got a plain message.
Refused,
/// The user was already blocked: the call wasn't attempted.
Blocked,
}
/// One entry of the security log: a suspected attack, or a bug when the names came from code.
public sealed record SecurityEvent(DateTimeOffset At, string User, string Action, string Kind, string Detail);
/// The outcome, the call's result when it ran, and the message to show the user (never the detection details).
public sealed record GuardResult(GuardOutcome Outcome, T? Value, string ForTheUser);
///
/// A security check around ARX calls: the pattern to copy into an application, kept small so it can be read in one
/// go. It lets every ARX error through except ARX1017 SuspectedInjection, which it turns into:
///
/// - an entry in the security log (), with the user, the action and ARX's message (the name is
/// escaped and cut to 64 characters by ARX, so it is safe to log);
/// - a plain message for the user that doesn't say what was detected;
/// - a strike against the user. After blockAfter strikes the user is blocked and their calls aren't attempted.
/// One strike never blocks anyone, so a single false positive only costs one refused request;
/// - no strike when the names came from your own code (): that's a bug to fix, logged
/// as one.
///
/// A false positive (a harmless name such as a file header E-mail (work) flagged as SQL) is handled by triage:
/// read the event, fix the mapping that let the name through, and the user if needed.
/// In a real application the log goes to your SIEM or security monitoring and the strikes live in a shared store
/// (Redis, the database), not in memory.
///
public sealed class SecurityGuard
{
private const string ATTACK = "suspected attack";
private const string BUG = "bug";
private readonly object _gate = new();
private readonly int _blockAfter;
private readonly Dictionary _strikes = new(StringComparer.Ordinal);
private readonly List _events = new();
public SecurityGuard(int blockAfter = 3)
{
_blockAfter = blockAfter;
}
/// The security log, oldest first.
public IReadOnlyList Events
{
get
{
lock (_gate)
{
return _events.ToArray();
}
}
}
public bool IsBlocked(string user)
{
lock (_gate)
{
return _strikes.TryGetValue(user, out var strikes) && strikes >= _blockAfter;
}
}
/// After triage found the events were a false positive: clears the user's strikes (the log is kept).
public void Unblock(string user)
{
lock (_gate)
{
_strikes.Remove(user);
}
}
/// Runs for unless they are blocked, and handles ARX1017 as described above.
public async Task> RunAsync(string user, string action, NameSource names, Func> call)
{
if (IsBlocked(user))
{
return new GuardResult(GuardOutcome.Blocked, default, "Your access is suspended. Contact support.");
}
try
{
return new GuardResult(GuardOutcome.Done, await call(), "Done.");
}
catch (ArxValidationException error) when (error.Code == ArxErrorCode.SuspectedInjection)
{
lock (_gate)
{
if (names == NameSource.Code)
{
_events.Add(new SecurityEvent(DateTimeOffset.UtcNow, user, action, BUG, error.Message));
return new GuardResult(GuardOutcome.Refused, default, "Something went wrong on our side. It has been reported.");
}
_strikes[user] = _strikes.GetValueOrDefault(user) + 1;
_events.Add(new SecurityEvent(DateTimeOffset.UtcNow, user, action, ATTACK, error.Message));
}
return new GuardResult(GuardOutcome.Refused, default, "The request couldn't be processed.");
}
}
}
```