Delta is an approach to implementing a 304 Not Modified leveraging DB change tracking.
The approach uses a last updated timestamp from the database to generate an ETag. All dynamic requests then have that ETag checked/applied.
This approach works well when the frequency of updates is relatively low. In this scenario, the majority of requests will leverage the result in a 304 Not Modified being returned and the browser loading the content its cache.
Effectively consumers will always receive the most current data, while the load on the server remains low.
See Milestones for release notes.
Frequency of updates to data is relatively low compared to reads
For SQL Server the transaction log is used (via dm_db_log_stats) if the current user has the VIEW SERVER STATE permission.
If VIEW SERVER STATE is not allowed then a combination of Change Tracking and/or Row Versioning is used.
Give the above certain kinds of operations will be detected:
| Transaction Log | Change Tracking | Row Versioning | Change Tracking and Row Versioning |
|
|---|---|---|---|---|
| Insert | ✅ | ✅ | ✅ | ✅ |
| Update | ✅ | ✅ | ✅ | ✅ |
| Hard Delete | ✅ | ✅ | ❌ | ✅ |
| Soft Delete | ✅ | ✅ | ✅ | ✅ |
| Truncate | ✅ | ❌ | ❌ | ❌ |
Postgres required track_commit_timestamp to be enabled. This can be done using ALTER SYSTEM SET track_commit_timestamp to "on" and then restarting the Postgres service
graph TD
Request
CalculateEtag[Calculate current ETag<br/>based on timestamp<br/>from web assembly and SQL]
IfNoneMatch{Has<br/>If-None-Match<br/>header?}
EtagMatch{Current<br/>Etag matches<br/>If-None-Match?}
AddETag[Add current ETag<br/>to Response headers]
304[Respond with<br/>304 Not-Modified]
Request --> CalculateEtag
CalculateEtag --> IfNoneMatch
IfNoneMatch -->|Yes| EtagMatch
IfNoneMatch -->|No| AddETag
EtagMatch -->|No| AddETag
EtagMatch -->|Yes| 304
The ETag is calculated from a combination several parts
The last write time of the web entry point assembly
snippet: AssemblyWriteTime
Transaction log is used via dm_db_log_stats.
select log_end_lsn
from sys.dm_db_log_stats(db_id())A combination of change_tracking_current_version (if tracking is enabled) and @@DBTS (row version timestamp)
declare @changeTracking bigint = change_tracking_current_version();
declare @timeStamp bigint = convert(bigint, @@dbts);
if (@changeTracking is null)
select cast(@timeStamp as varchar)
else
select cast(@timeStamp as varchar) + '-' + cast(@changeTracking as varchar)select pg_last_committed_xact();An optional string suffix that is dynamically calculated at runtime based on the current HttpContext.
snippet: Suffix
snippet: BuildEtag
Delta is shipped as two nugets:
- Delta: Delivers functionality using SqlConnection and SqlTransaction.
- Delta.EF: Delivers functionality using SQL Server EF Database Provider.
Only one of the above should be used.
Example SQL schema:
snippet: Usage.Schema.verified.sql
Example SQL schema:
snippet: PostgresSchema
snippet: UseDeltaSqlServer
snippet: UseDeltaPostgres
To add to a specific Route Group:
snippet: UseDeltaMapGroup
Optionally control what requests Delta is executed on.
snippet: ShouldExecute
By default, Delta uses HttpContext.RequestServices to discover the SqlConnection and SqlTransaction:
snippet: DiscoverConnection
To use custom connection discovery:
snippet: CustomDiscoveryConnection
To use custom connection and transaction discovery:
snippet: CustomDiscoveryConnectionAndTransaction
Enable row versioning in Entity Framework
snippet: SampleSqlServerDbContext
Enable row versioning in Entity Framework
snippet: SamplePostgresDbContext
snippet: UseDeltaSQLServerEF
snippet: UseDeltaPostgresEF
To add to a specific Route Group:
snippet: UseDeltaMapGroupEF
Optionally control what requests Delta is executed on.
snippet: ShouldExecuteEF
Response diagnostics is an opt-in feature that includes extra log information in the response headers.
Enable by setting UseResponseDiagnostics to true at startup:
snippet: UseResponseDiagnostics
Response diagnostics headers are prefixed with Delta-.
Example Response header when the Request has not If-None-Match header.
A set of helper methods for working with SQL Server Change Tracking and SQL Server Row Versioning
Nuget: Delta.SqlServer
snippet: GetLastTimeStampSqlConnection
snippet: GetLastTimeStampEF
Get a list of all databases with change tracking enabled.
snippet: GetDatabasesWithTracking
Uses the following SQL:
snippet: GetTrackedDatabasesSql
Get a list of all tracked tables in database.
snippet: GetTrackedTables
Uses the following SQL:
snippet: GetTrackedTablesSql
Determine if change tracking is enabled for a database.
snippet: IsTrackingEnabled
Uses the following SQL:
snippet: IsTrackingEnabledSql
Enable change tracking for a database.
snippet: EnableTracking
Uses the following SQL:
snippet: EnableTrackingSql
Disable change tracking for a database and all tables within that database.
snippet: DisableTracking
Uses the following SQL:
snippet: DisableTrackingSqlDB
snippet: DisableTrackingSqlTable
Enables change tracking for all tables listed, and disables change tracking for all tables not listed.
snippet: SetTrackedTables
Uses the following SQL:
snippet: EnableTrackingSql
snippet: EnableTrackingTableSql
snippet: DisableTrackingTableSql
The behavior of Delta can be verified as follows:
- Open a page in the site
- Open the browser developer tools
- Change to the Network tab
- Refresh the page.
Cached responses will show as 304 in the Status:
In the headers if-none-match will show in the request and etag will show in the response:
If disable cache is checked, the browser will not send the if-none-match header. This will effectively cause a cache miss server side, and the full server pipeline will execute.
Chromium, and hence the Chrome and Edge browsers, are very sensitive to certificate problems when determining if an item should be cached. Specifically, if a request is done dynamically (type: xhr) and the server is using a self-signed certificate, then the browser will not send the if-none-match header. Reference. If self-signed certificates are required during development in lower environment, then use FireFox to test the caching behavior.
Delta is primarily designed to support web browsers as a client. All web browsers have the necessary 304 and caching functionally required.
In the scenario where web apis (that support using 304) are being consumed using .net as a client, consider using one of the below extensions to cache responses.
Estuary designed by Daan from The Noun Project.