fixed nil pointer

.gcloudignore

@@ -6,4 +6,5 @@ e2e/
 .gitignore
 *.yaml
 *.md
-secrets.json
+secrets.json
+.meta

.gitignore

@@ -2,20 +2,18 @@
 secrets.json
 *.db
 local_test.go
-vendor
+vendor/
 datly
 other
 mydb
 tmp/
 *.gz
 .DS_Store
 autogen
-dql
-dql
 *.iml
 *.so
 logs
 .extension
 .datly
 *.zip
-local
+v1/

Version

@@ -1 +1 @@
-v0.20.2
+v0.38.0

cache-management.md

@@ -0,0 +1,152 @@
+# Cache management
+
+Datly uses SQLX main revision `031ed89ced07` and xdatly/handler revision
+`34eaa9f4902b`, and adds persistent, view-scoped generations to native
+cache identities. Both request-populated (lazy) and prewarmed entries remain
+subject to their configured TTL.
+
+## Invalidate a component or view
+
+For a GET component at `/v1/api/orders`, Datly registers:
+
+```http
+POST /v1/api/cache/invalidate/orders
+Content-Type: application/json
+
+{"scope":"all"}
+```
+
+The path follows the same component-prefix mapping as the existing warmup route.
+`Meta.CacheInvalidateURI` configures the prefix, defaulting to
+`/v1/api/cache/invalidate`.
+
+- `all` (default) retires lazy entries and warmup publications.
+- `lazy` retires request-populated entries only. Warmup hits remain eligible.
+- `warmup` retires prewarmed entries only. Existing lazy hits remain eligible.
+- `view` optionally selects a view by name, including a nested view. Omitting it
+  selects every cached view reachable through the component's `With` relations,
+  including views without a warmup configuration.
+
+```json
+{"view":"order_items","scope":"lazy"}
+```
+
+An empty request body defaults to `all`. The response reports each view's scope
+and new generation. Unknown views return 404; invalid JSON, unknown properties,
+and invalid scopes return 400. Storage failures return 500 with per-view results;
+a multi-view request is not a transaction, so some views can succeed while others
+fail. Retrying invalidation is safe.
+
+The route inherits the component's API-key requirements and the gateway's subnet
+policy. Invalidating caches requires the same deployment access controls as other
+administrative routes. Rejected API keys stop execution before any mutation.
+
+## Repopulate after invalidation
+
+Invalidation does not query the database. The next request fills a lazy entry.
+To repopulate configured warmups, call the existing route after invalidation:
+
+```http
+POST /v1/api/cache/warmup/orders
+```
+
+Use `all` before warming if previously populated lazy results must also be
+retired. `warmup` alone intentionally preserves lazy results. Invalidating a
+warmup retires every configured warmup case for the selected view.
+
+A forced reader cache refresh retires both generations for the view before
+reading. This is intentionally broader than an exact-query refresh, and prevents
+Aerospike from satisfying the refresh with an older warmup publication.
+
+## Storage and concurrency
+
+A cache owner is derived from the resource identity, view name, and connector
+configuration. Resource paths below `/routes/` are made route-relative so replicas
+with different deployment roots agree. Views with the same owner intentionally
+share their cache; invalidation affects that shared view wherever it is used.
+Standalone resources outside `/routes/` need consistent resource URLs across
+replicas. Read SQL is unchanged. Warmup queries receive a cache-identity SQL
+comment; query semantics and bound arguments are unchanged.
+
+AFS stores generation files under `<expanded location>/.datly-generations/<owner>`.
+Local generation changes use atomic file replacement. Object-storage deployments
+must provide atomic object replacement and read-after-write consistency for these
+control objects. Aerospike stores a permanent control record per owner, with
+independent `all`, `lazy`, and `warmup` bins. Concurrent scope changes do not
+replace one another's bins.
+
+Readers obtain the shared generation on every lookup. Operations already in
+flight may finish using their captured generation. A writer that started before
+invalidation can only publish into its old generation; later lookups cannot use
+it. All cache instances must use the same underlying storage to share invalidation;
+separate local disks and per-process memory caches are independently managed.
+
+Generation controls must be retained and excluded from external cache cleanup or
+Aerospike eviction. Removing control state while retaining payloads can make old
+generations reachable. Invalidation is logical, not a storage purge. Aerospike
+reclaims old payloads through its TTL. AFS does not run a background garbage
+collector: retain your storage lifecycle/cleanup policy for expired JSON payloads,
+excluding `.datly-generations`.
+
+Upgrading introduces a new cache-key namespace, so existing cache entries are
+cold until lazily refilled or prewarmed. Existing payloads need normal cleanup.
+
+## TTL and location configuration
+
+`TimeToLiveMs` must be positive and fit in a Go duration. For Aerospike, it must
+be an exact number of seconds; subsecond/fractional-second values and reserved
+server TTL values are rejected instead of truncated. For example, use `1000` or
+`60000`, not `500` or `1500`. AFS supports millisecond TTLs.
+
+Cache-provider locations support view expansion:
+
+```yaml
+CacheProviders:
+  - Name: local
+    Location: /cache/${View.Name}
+    TimeToLiveMs: 60000
+```
+
+`${View.Alias}` and `${View.Table}` are also supported. The escaped-dot forms
+(`${View\.Name}`, `${View\.Alias}`, `${View\.Table}`) are accepted too. For Aerospike the expanded
+location is the set name and must satisfy Aerospike's set-name rules.
+
+## Verification
+
+The managed-cache tests exercise native AFS/SQLite cache reads and writes, TTL
+expiry, both warmup forms, scope isolation, owner isolation, refresh, persistence
+across cache instances, and invalidation during lazy/warmup writes. HTTP tests
+cover nested lazy-only views, input errors, and API-key rejection. Generation-store
+tests cover concurrent file publication and Aerospike's independent bins and
+nonexpiring control-record write policy.
+
+A live Aerospike test is available against a dedicated test server:
+
+```sh
+DATLY_TEST_AEROSPIKE=aerospike://127.0.0.1:3000/test \
+  go test ./internal/cache/managed -run TestManagedAerospikeIntegration -count=1 -v
+```
+
+The existing `e2e/local/system.yaml` uses Aerospike `ce-6.2.0.2` at that address.
+The test uses unique owner identities in `datly_cache_test`, short payload TTLs,
+and removes its own generation records. It does not truncate a namespace or set.
+It is skipped when `DATLY_TEST_AEROSPIKE` is unset.
+
+## Creation metrics
+
+Per-view counters expose `cache:created`, `cache:lazy_created`, and
+`cache:warmup_created`. These count successfully published cache entries, not
+lookup misses or write attempts. Index markers count as entries; overflow chunks
+do not. Hits, reused AFS warmups, failed writes, and rolled-back requests do not
+increment creation counters. Empty results count when their cache entry or index
+marker is published. `cache:miss_write` remains the separate write-attempt counter.
+
+SQLX caches with `SetCreationObserver(func(kind string, entries int))` report
+both lazy and warmup publications. Cache implementations without the observer use Datly's successful
+lazy-close fallback; exact warmup creation counts require the native observer.
+Existing warmup run/group metrics remain available independently.
+
+With the updated shared response contract, SQL execution metrics expose
+`cacheStats.createdTime` alongside `expiryTime`. Creation time is persisted by
+SQLX and stays unchanged on cache hits. Legacy entries without a stored creation
+time omit the field. Datly copies the timestamp after cache publication completes.

cmd/cli.go

@@ -3,13 +3,13 @@ package cmd
 import (
 	"context"
 	"fmt"
+
 	"github.com/jessevdk/go-flags"
 	"github.com/viant/datly/cmd/command"
 	soptions "github.com/viant/datly/cmd/options"
 )
 
 func RunApp(version string, args soptions.Arguments) error {
-
 	options, err := buildOptions(args)
 	if err != nil {
 		return err

cmd/command/async_defaults.go

@@ -0,0 +1,33 @@
+package command
+
+import (
+	"github.com/viant/afs/file"
+	"github.com/viant/afs/url"
+	"github.com/viant/datly/gateway/runtime/standalone"
+)
+
+const (
+	defaultJobURL       = "/tmp/datly/jobs"
+	defaultFailedJobURL = "/tmp/datly/failed"
+)
+
+func applyAsyncJobDefaults(config *standalone.Config) {
+	if config == nil {
+		return
+	}
+
+	if config.JobURL == "" && config.FailedJobURL == "" {
+		config.JobURL = defaultJobURL
+		config.FailedJobURL = defaultFailedJobURL
+		return
+	}
+
+	if config.JobURL == "" {
+		config.JobURL = defaultJobURL
+	}
+
+	if config.FailedJobURL == "" {
+		parent, _ := url.Split(config.JobURL, file.Scheme)
+		config.FailedJobURL = url.Join(parent, "failed", "jobs")
+	}
+}

cmd/command/async_defaults_test.go

@@ -0,0 +1,51 @@
+package command
+
+import (
+	"testing"
+
+	"github.com/viant/datly/gateway"
+	"github.com/viant/datly/gateway/runtime/standalone"
+)
+
+func TestApplyAsyncJobDefaults(t *testing.T) {
+	testCases := []struct {
+		name         string
+		jobURL       string
+		failedJobURL string
+		expectJob    string
+		expectFailed string
+	}{
+		{
+			name:         "both empty use tmp defaults",
+			expectJob:    "/tmp/datly/jobs",
+			expectFailed: "/tmp/datly/failed",
+		},
+		{
+			name:         "custom job only derives failed path",
+			jobURL:       "/custom/jobs",
+			expectJob:    "/custom/jobs",
+			expectFailed: "file://localhost/custom/failed/jobs",
+		},
+		{
+			name:         "failed only keeps failed and defaults job",
+			failedJobURL: "/custom/failed",
+			expectJob:    "/tmp/datly/jobs",
+			expectFailed: "/custom/failed",
+		},
+	}
+
+	for _, testCase := range testCases {
+		cfg := &standalone.Config{Config: &gateway.Config{}}
+		cfg.JobURL = testCase.jobURL
+		cfg.FailedJobURL = testCase.failedJobURL
+
+		applyAsyncJobDefaults(cfg)
+
+		if cfg.JobURL != testCase.expectJob {
+			t.Fatalf("%s: expected JobURL=%s, got %s", testCase.name, testCase.expectJob, cfg.JobURL)
+		}
+		if cfg.FailedJobURL != testCase.expectFailed {
+			t.Fatalf("%s: expected FailedJobURL=%s, got %s", testCase.name, testCase.expectFailed, cfg.FailedJobURL)
+		}
+	}
+}