# The ARX.SDK sample application for MongoDB
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.MongoDb;
/// 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 MongoDB driver 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.MongoDb;
/// 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 ARX service and its schema catalog, created once and shared by the samples.
```csharp
using ARX.SDK.MongoDb.Services;
using ARX.SDK.Services;
namespace ArxSamples.MongoDb;
/// The application's ARX service and its schema catalog, shared by the real and advanced samples.
public sealed partial class SampleContext
{
private ArxSchemaCatalog? _catalog;
private ArxMongoDbService? _service;
/// The application's schema catalog: collection ids, keys, lookups and selection sets (SampleCatalog.cs).
public ArxSchemaCatalog Catalog => _catalog ??= SampleCatalog.Build();
///
/// One service for the whole application. It shares one MongoDB client per connection string (a client is a
/// connection pool), so make it once and keep it.
///
public ArxMongoDbService Service => _service ??= new ArxMongoDbService(ConnectionString, Catalog);
}
```
## SampleCatalog.cs
The application's schema catalog: every table's id column and keys, and its selection sets.
```csharp
using ARX.SDK.Services;
namespace ArxSamples.MongoDb;
/// An account's industry. Stored in account.industry as the enum's number.
public enum Industry
{
Retail = 1,
Manufacturing = 2,
Healthcare = 3,
Finance = 4,
Technology = 5
}
///
/// The application's schema catalog: every collection's id and keys, the lookups between collections, and every
/// picklist (selection set), defined once.
///
///
///
/// Ids. On MongoDB the declared id is the document's _id, named in your code by the column you declare
/// (account["account_id"]). A generated string id is an ObjectId ARX makes before the insert and gives back as its
/// 24-character text; a generated Guid is one ARX makes; a supplied id is yours (a country code, a SKU). MongoDB has no
/// sequences, so a generated number isn't offered, and every document has an _id, so there is no NoIdColumn.
///
///
/// Keys. Business keys (an account number; a region and a SKU together) let Update, Delete and Retrieve find
/// documents by them. MongoDB enforces them with unique indexes: the sample database has one for each.
///
///
/// Lookups. MongoDB has no foreign keys, so the catalog says which field refers to which collection
/// (.Lookup("contact", "account_id", "account")). ARX stores the referenced id as it is stored there (an ObjectId)
/// and reads the field back as an with the referenced record's display name.
///
///
/// Selection sets. A field that only accepts a fixed list of codes: an account's status, a contact's preferred
/// channels (several codes, stored as an array). ARX checks every against the catalog
/// before anything is sent and stores the codes themselves.
///
///
public static class SampleCatalog
{
public static ArxSchemaCatalog Build() => ArxSchemaCatalog.Create()
.Table("account", ArxIdColumn.Generated("account_id"))
.Key("account", "account_number")
.DisplayName("account", "name")
.Table("contact", ArxIdColumn.Generated("contact_id"))
.Key("contact", "email")
.Lookup("contact", "account_id", "account")
.DisplayName("contact", new[] { "first_name", "last_name" }, " ")
.Table("country", ArxIdColumn.Supplied("code"))
.DisplayName("country", "name")
.Table("product", ArxIdColumn.Supplied("sku"))
.DisplayName("product", "name")
.Table("price_list", ArxIdColumn.Generated("price_id"))
.Key("price_list", "region", "sku")
.Lookup("price_list", "region", "country")
.Table("sales_order", ArxIdColumn.Generated("order_id"))
.Key("sales_order", "order_number")
.Lookup("sales_order", "account_id", "account")
.Table("activity_log", ArxIdColumn.Generated("log_id"))
.AddEnum("Industry")
.Add("AccountStatus", ArxSelectionSetKind.String, ("ACTIVE", "Active"), ("ON_HOLD", "On hold"), ("CLOSED", "Closed"))
.Add("ContactChannels", ArxSelectionSetKind.String, ArxSelectionSetMultiplicity.Array, ("E", "Email"), ("P", "Phone"), ("S", "SMS"))
.Build();
}
```
## SecurityGuard.cs
A security check around ARX calls: suspected injection logged as a security event, strikes, blocking.
```csharp
using ARX.SDK;
namespace ArxSamples.MongoDb;
/// 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.");
}
}
}
```