Class: Rafflesia::Cache

Inherits:
Object
  • Object
show all
Defined in:
lib/rafflesia/cache.rb

Instance Method Summary collapse

Constructor Details

#initialize(client) ⇒ Cache

Returns a new instance of Cache.



9
10
11
 
# File 'lib/rafflesia/cache.rb', line 9

def initialize(client)
  @client = client
end

Instance Method Details

#admission(estimated_size_bytes:, target_dir:, candidate_object_ids: nil, candidate_ref: nil, expected_reuse_count: nil, max_bytes: nil, namespace: nil, older_than_seconds: nil, pinned_paths: nil, policy: nil, priority: nil, require_free_capacity: nil, workload: nil, workload_profile: nil, request_options: {}) ⇒ Rafflesia::EnvelopeCacheAdmissionData

POST /v1/cache/admission

Parameters:

  • candidate_object_ids (Array<String>, nil) (defaults to: nil) —

    Candidate content-addressed objects that would be admitted.

  • candidate_ref (String, nil) (defaults to: nil) —

    Caller-visible candidate ref, such as an index ref or manifest object id.

  • estimated_size_bytes (Integer) —

    Estimated local cache bytes needed for the candidate.

  • expected_reuse_count (Integer, nil) (defaults to: nil) —

    Expected number of reuses during the caller's planning horizon.

  • max_bytes (Integer, nil) (defaults to: nil) —

    Optional cache byte budget override.

  • namespace (String, nil) (defaults to: nil) —

    Logical cache namespace for the candidate.

  • older_than_seconds (Integer, nil) (defaults to: nil) —

    Optional TTL filter for pressure planning.

  • pinned_paths (Array<String>, nil) (defaults to: nil) —

    Paths that must not be evicted while considering admission.

  • policy (Rafflesia::CacheEvictionPolicy, nil) (defaults to: nil) —

    Optional cache policy object.

  • priority (Integer, nil) (defaults to: nil) —

    Optional caller priority. Zero means normal priority.

  • require_free_capacity (Boolean, nil) (defaults to: nil) —

    When true, reject admission if the candidate cannot fit without deleting eligible bytes.

  • target_dir (String) —

    Local cache directory that would receive the candidate.

  • workload (String, nil) (defaults to: nil) —

    Workload requesting cache admission, for example blast, blast_search, fold_index, or object_artifact.

  • workload_profile (String, nil) (defaults to: nil) —

    Optional serverless workload profile whose cache policy should be applied.

  • request_options (Hash) (defaults to: {}) —

    (see Rafflesia::Types::RequestOptions)

Returns:



30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/rafflesia/cache.rb', line 30

def admission(
  estimated_size_bytes:,
  target_dir:,
  candidate_object_ids: nil,
  candidate_ref: nil,
  expected_reuse_count: nil,
  max_bytes: nil,
  namespace: nil,
  older_than_seconds: nil,
  pinned_paths: nil,
  policy: nil,
  priority: nil,
  require_free_capacity: nil,
  workload: nil,
  workload_profile: nil,
  request_options: {}
)
  body = {
    'candidate_object_ids' => candidate_object_ids,
    'candidate_ref' => candidate_ref,
    'estimated_size_bytes' => estimated_size_bytes,
    'expected_reuse_count' => expected_reuse_count,
    'max_bytes' => max_bytes,
    'namespace' => namespace,
    'older_than_seconds' => older_than_seconds,
    'pinned_paths' => pinned_paths,
    'policy' => policy,
    'priority' => priority,
    'require_free_capacity' => require_free_capacity,
    'target_dir' => target_dir,
    'workload' => workload,
    'workload_profile' => workload_profile
  }.compact
  response = @client.request(
    method: :post,
    path: '/v1/cache/admission',
    auth: true,
    body: body,
    request_options: request_options
  )
  result = Rafflesia::EnvelopeCacheAdmissionData.new(response.body)
  result.last_response = Rafflesia::Types::ApiResponse.new(http_status: response.code.to_i, http_headers: response.each_header.to_h, request_id: response["x-request-id"])
  result
end

#benchmark(workload:, db: nil, evalue: nil, evict_first: nil, manifest_object_id: nil, manifest_path: nil, max_target_seqs: nil, min_bit_score: nil, out_format: nil, pack_access_mode: nil, pressure_max_bytes: nil, program: nil, query: nil, ref: nil, run_pressure: nil, segment_roles: nil, shards: nil, target_dir: nil, threads: nil, verify: nil, request_options: {}) ⇒ Rafflesia::EnvelopeCacheBenchmarkData

POST /v1/cache/benchmark

Parameters:

  • db (String, nil) (defaults to: nil) —

    BLAST DB ref, manifest path, or local prefix for blast_search benchmarks.

  • evalue (String, nil) (defaults to: nil) —

    BLAST E-value threshold for blast_search benchmarks.

  • evict_first (Boolean, nil) (defaults to: nil) —

    Evict the selected cache before the cold materialization measurement.

  • manifest_object_id (String, nil) (defaults to: nil) —

    Manifest object id for object_artifact or fold_index workloads.

  • manifest_path (String, nil) (defaults to: nil) —

    Local manifest path for object_artifact, blast, diamond, or fold_index workloads.

  • max_target_seqs (Integer, nil) (defaults to: nil) —

    Maximum BLAST targets for blast_search benchmarks; defaults to 100.

  • min_bit_score (Float, nil) (defaults to: nil) —

    Optional hit filter for blast_search benchmarks.

  • out_format (String, nil) (defaults to: nil) —

    BLAST outfmt for blast_search benchmarks; defaults to deterministic tabular fields.

  • pack_access_mode (Rafflesia::Types::CacheBenchmarkRequestPackAccessMode, nil) (defaults to: nil) —

    Pack access mode forwarded to blast_search benchmarks.

  • pressure_max_bytes (Integer, nil) (defaults to: nil) —

    Max-bytes value used for the optional dry-run pressure eviction measurement.

  • program (String, nil) (defaults to: nil) —

    BLAST program for blast_search benchmarks; defaults to blastp.

  • query (String, nil) (defaults to: nil) —

    Query FASTA path or cached sequence id for blast_search benchmarks.

  • ref (String, nil) (defaults to: nil) —

    Published BLAST DB, DIAMOND DB, or Foldseek index ref.

  • run_pressure (Boolean, nil) (defaults to: nil) —

    Run a dry-run pressure eviction measurement after warm materialization.

  • segment_roles (Array<String>, nil) (defaults to: nil) —

    Optional Foldseek segment roles for fold_index workloads: search_index, routing_index.

  • shards (Array<String>, nil) (defaults to: nil) —

    Optional shard ids for object_artifact and fold_index workloads.

  • target_dir (String, nil) (defaults to: nil) —

    Local cache root used for materialization.

  • threads (Integer, nil) (defaults to: nil) —

    BLAST thread count for blast_search benchmarks; defaults to 1.

  • verify (Boolean, nil) (defaults to: nil) —

    Verify materialized files by SHA-256.

  • workload (Rafflesia::Types::CacheBenchmarkRequestWorkload) —

    Cache workload to measure.

  • request_options (Hash) (defaults to: {}) —

    (see Rafflesia::Types::RequestOptions)

Returns:



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/rafflesia/cache.rb', line 98

def benchmark(
  workload:,
  db: nil,
  evalue: nil,
  evict_first: nil,
  manifest_object_id: nil,
  manifest_path: nil,
  max_target_seqs: nil,
  min_bit_score: nil,
  out_format: nil,
  pack_access_mode: nil,
  pressure_max_bytes: nil,
  program: nil,
  query: nil,
  ref: nil,
  run_pressure: nil,
  segment_roles: nil,
  shards: nil,
  target_dir: nil,
  threads: nil,
  verify: nil,
  request_options: {}
)
  body = {
    'db' => db,
    'evalue' => evalue,
    'evict_first' => evict_first,
    'manifest_object_id' => manifest_object_id,
    'manifest_path' => manifest_path,
    'max_target_seqs' => max_target_seqs,
    'min_bit_score' => min_bit_score,
    'out_format' => out_format,
    'pack_access_mode' => pack_access_mode,
    'pressure_max_bytes' => pressure_max_bytes,
    'program' => program,
    'query' => query,
    'ref' => ref,
    'run_pressure' => run_pressure,
    'segment_roles' => segment_roles,
    'shards' => shards,
    'target_dir' => target_dir,
    'threads' => threads,
    'verify' => verify,
    'workload' => workload
  }.compact
  response = @client.request(
    method: :post,
    path: '/v1/cache/benchmark',
    auth: true,
    body: body,
    request_options: request_options
  )
  result = Rafflesia::EnvelopeCacheBenchmarkData.new(response.body)
  result.last_response = Rafflesia::Types::ApiResponse.new(http_status: response.code.to_i, http_headers: response.each_header.to_h, request_id: response["x-request-id"])
  result
end

#benchmarkSuite(benchmarks:, max_total_lock_wait_ms: nil, max_warm_object_read_bytes: nil, require_cold_object_reads: nil, require_pressure_plan: nil, require_warm_cache_hits: nil, require_zero_warm_object_reads: nil, store_artifact: nil, suite_name: nil, suite_version: nil, workload_profile: nil, request_options: {}) ⇒ Rafflesia::EnvelopeCacheBenchmarkSuiteData

POST /v1/cache/benchmark-suite

Parameters:

  • benchmarks (Array<Rafflesia::CacheBenchmarkRequest>, nil) —

    Cache benchmark cases to run sequentially.

  • max_total_lock_wait_ms (Integer, nil) (defaults to: nil) —

    Maximum aggregate materialization lock wait across one case. Zero disables this gate.

  • max_warm_object_read_bytes (Integer, nil) (defaults to: nil) —

    Maximum warm object bytes per case. Zero disables this gate.

  • require_cold_object_reads (Boolean, nil) (defaults to: nil) —

    Require each case to perform at least one cold object read.

  • require_pressure_plan (Boolean, nil) (defaults to: nil) —

    Require each case to include a pressure_evict_dry_run step.

  • require_warm_cache_hits (Boolean, nil) (defaults to: nil) —

    Require each warm case to reuse local cache files without cache misses.

  • require_zero_warm_object_reads (Boolean, nil) (defaults to: nil) —

    Require each warm case to perform zero object-store reads.

  • store_artifact (Boolean, nil) (defaults to: nil) —

    Store the suite response as a content-addressed JSON object.

  • suite_name (String, nil) (defaults to: nil) —

    Human-readable benchmark suite name.

  • suite_version (String, nil) (defaults to: nil) —

    Caller-controlled suite version or corpus snapshot.

  • workload_profile (String, nil) (defaults to: nil) —

    Optional serverless workload profile used to evaluate workload gates.

  • request_options (Hash) (defaults to: {}) —

    (see Rafflesia::Types::RequestOptions)

Returns:



169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/rafflesia/cache.rb', line 169

def benchmarkSuite(
  benchmarks:,
  max_total_lock_wait_ms: nil,
  max_warm_object_read_bytes: nil,
  require_cold_object_reads: nil,
  require_pressure_plan: nil,
  require_warm_cache_hits: nil,
  require_zero_warm_object_reads: nil,
  store_artifact: nil,
  suite_name: nil,
  suite_version: nil,
  workload_profile: nil,
  request_options: {}
)
  body = {
    'benchmarks' => benchmarks,
    'max_total_lock_wait_ms' => max_total_lock_wait_ms,
    'max_warm_object_read_bytes' => max_warm_object_read_bytes,
    'require_cold_object_reads' => require_cold_object_reads,
    'require_pressure_plan' => require_pressure_plan,
    'require_warm_cache_hits' => require_warm_cache_hits,
    'require_zero_warm_object_reads' => require_zero_warm_object_reads,
    'store_artifact' => store_artifact,
    'suite_name' => suite_name,
    'suite_version' => suite_version,
    'workload_profile' => workload_profile
  }.compact
  response = @client.request(
    method: :post,
    path: '/v1/cache/benchmark-suite',
    auth: true,
    body: body,
    request_options: request_options
  )
  result = Rafflesia::EnvelopeCacheBenchmarkSuiteData.new(response.body)
  result.last_response = Rafflesia::Types::ApiResponse.new(http_status: response.code.to_i, http_headers: response.each_header.to_h, request_id: response["x-request-id"])
  result
end

#explain(cache_key:, namespace:, request_options: {}) ⇒ Rafflesia::EnvelopeCacheExplainData

POST /v1/cache/explain

Parameters:

  • cache_key (String) —

    Deterministic cache key returned by the primitive response.

  • namespace (String) —

    Cache namespace, for example msa_build, profile_build, or materialization.

  • request_options (Hash) (defaults to: {}) —

    (see Rafflesia::Types::RequestOptions)

Returns:



213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
 
# File 'lib/rafflesia/cache.rb', line 213

def explain(
  cache_key:,
  namespace:,
  request_options: {}
)
  body = {
    'cache_key' => cache_key,
    'namespace' => namespace
  }
  response = @client.request(
    method: :post,
    path: '/v1/cache/explain',
    auth: true,
    body: body,
    request_options: request_options
  )
  result = Rafflesia::EnvelopeCacheExplainData.new(response.body)
  result.last_response = Rafflesia::Types::ApiResponse.new(http_status: response.code.to_i, http_headers: response.each_header.to_h, request_id: response["x-request-id"])
  result
end

#status(target_dir:, include_files: nil, max_bytes: nil, max_files: nil, namespace: nil, older_than_seconds: nil, pinned_paths: nil, policy: nil, workload_profile: nil, request_options: {}) ⇒ Rafflesia::EnvelopeCacheStatusData

POST /v1/cache/status

Parameters:

  • include_files (Boolean, nil) (defaults to: nil) —

    Include sampled cache file rows in the response.

  • max_bytes (Integer, nil) (defaults to: nil) —

    Optional cache byte budget. If omitted, policy.max_bytes or the workload profile budget is used when available.

  • max_files (Integer, nil) (defaults to: nil) —

    Maximum cache file rows to include when include_files is true. Defaults to 100.

  • namespace (String, nil) (defaults to: nil) —

    Logical cache namespace recorded in the response.

  • older_than_seconds (Integer, nil) (defaults to: nil) —

    Optional TTL filter for eviction pressure planning. Age basis is mtime.

  • pinned_paths (Array<String>, nil) (defaults to: nil) —

    Absolute paths, target-dir-relative paths, or file basenames that must not be evicted.

  • policy (Rafflesia::CacheEvictionPolicy, nil) (defaults to: nil) —

    Optional policy object; top-level fields override empty policy fields.

  • target_dir (String) —

    Local cache directory to inspect recursively.

  • workload_profile (String, nil) (defaults to: nil) —

    Optional serverless workload profile whose cache pressure policy should be applied.

  • request_options (Hash) (defaults to: {}) —

    (see Rafflesia::Types::RequestOptions)

Returns:



246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
 
# File 'lib/rafflesia/cache.rb', line 246

def status(
  target_dir:,
  include_files: nil,
  max_bytes: nil,
  max_files: nil,
  namespace: nil,
  older_than_seconds: nil,
  pinned_paths: nil,
  policy: nil,
  workload_profile: nil,
  request_options: {}
)
  body = {
    'include_files' => include_files,
    'max_bytes' => max_bytes,
    'max_files' => max_files,
    'namespace' => namespace,
    'older_than_seconds' => older_than_seconds,
    'pinned_paths' => pinned_paths,
    'policy' => policy,
    'target_dir' => target_dir,
    'workload_profile' => workload_profile
  }.compact
  response = @client.request(
    method: :post,
    path: '/v1/cache/status',
    auth: true,
    body: body,
    request_options: request_options
  )
  result = Rafflesia::EnvelopeCacheStatusData.new(response.body)
  result.last_response = Rafflesia::Types::ApiResponse.new(http_status: response.code.to_i, http_headers: response.each_header.to_h, request_id: response["x-request-id"])
  result
end

#sweep(target_dir:, apply: nil, dry_run: nil, max_bytes: nil, namespace: nil, older_than_seconds: nil, pinned_paths: nil, policy: nil, request_options: {}) ⇒ Rafflesia::EnvelopeCacheSweepData

POST /v1/cache/sweep

Parameters:

  • apply (Boolean, nil) (defaults to: nil) —

    Delete selected files. When false, generic cache sweep is forced to dry-run.

  • dry_run (Boolean, nil) (defaults to: nil) —

    List selected cache files without deleting them. Generic cache sweep defaults to dry-run unless apply is true.

  • max_bytes (Integer, nil) (defaults to: nil) —

    If positive, evict oldest eligible files until eligible bytes are less than or equal to this value. Zero selects every eligible file, but files are only deleted when apply is true.

  • namespace (String, nil) (defaults to: nil) —

    Logical cache namespace recorded in the response.

  • older_than_seconds (Integer, nil) (defaults to: nil) —

    If positive, only files whose modification time is at least this old are eligible. Age basis is mtime.

  • pinned_paths (Array<String>, nil) (defaults to: nil) —

    Absolute paths, target-dir-relative paths, or file basenames that must not be evicted.

  • policy (Rafflesia::CacheEvictionPolicy, nil) (defaults to: nil) —

    Optional policy object; top-level fields override empty policy fields.

  • target_dir (String) —

    Local cache directory to sweep recursively.

  • request_options (Hash) (defaults to: {}) —

    (see Rafflesia::Types::RequestOptions)

Returns:



292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
 
# File 'lib/rafflesia/cache.rb', line 292

def sweep(
  target_dir:,
  apply: nil,
  dry_run: nil,
  max_bytes: nil,
  namespace: nil,
  older_than_seconds: nil,
  pinned_paths: nil,
  policy: nil,
  request_options: {}
)
  body = {
    'apply' => apply,
    'dry_run' => dry_run,
    'max_bytes' => max_bytes,
    'namespace' => namespace,
    'older_than_seconds' => older_than_seconds,
    'pinned_paths' => pinned_paths,
    'policy' => policy,
    'target_dir' => target_dir
  }.compact
  response = @client.request(
    method: :post,
    path: '/v1/cache/sweep',
    auth: true,
    body: body,
    request_options: request_options
  )
  result = Rafflesia::EnvelopeCacheSweepData.new(response.body)
  result.last_response = Rafflesia::Types::ApiResponse.new(http_status: response.code.to_i, http_headers: response.each_header.to_h, request_id: response["x-request-id"])
  result
end

#warm(workloads:, continue_on_error: nil, target_dir: nil, verify: nil, request_options: {}) ⇒ Rafflesia::EnvelopeCacheWarmData

POST /v1/cache/warm

Parameters:

  • continue_on_error (Boolean, nil) (defaults to: nil) —

    Continue warming later workloads after one fails.

  • target_dir (String, nil) (defaults to: nil) —

    Default local cache root used for workload materialization.

  • verify (Boolean, nil) (defaults to: nil) —

    Verify materialized files by SHA-256.

  • workloads (Array<Rafflesia::CacheWarmWorkloadRequest>, nil) —

    Workloads to materialize before serving search traffic.

  • request_options (Hash) (defaults to: {}) —

    (see Rafflesia::Types::RequestOptions)

Returns:



332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
 
# File 'lib/rafflesia/cache.rb', line 332

def warm(
  workloads:,
  continue_on_error: nil,
  target_dir: nil,
  verify: nil,
  request_options: {}
)
  body = {
    'continue_on_error' => continue_on_error,
    'target_dir' => target_dir,
    'verify' => verify,
    'workloads' => workloads
  }.compact
  response = @client.request(
    method: :post,
    path: '/v1/cache/warm',
    auth: true,
    body: body,
    request_options: request_options
  )
  result = Rafflesia::EnvelopeCacheWarmData.new(response.body)
  result.last_response = Rafflesia::Types::ApiResponse.new(http_status: response.code.to_i, http_headers: response.each_header.to_h, request_id: response["x-request-id"])
  result
end

#workloadProfiles(workload: nil, request_options: {}) ⇒ Rafflesia::EnvelopeServerlessWorkloadProfileListData

POST /v1/cache/workload-profiles

Parameters:

  • workload (String, nil) (defaults to: nil) —

    Optional workload filter, for example blast or foldseek.

  • request_options (Hash) (defaults to: {}) —

    (see Rafflesia::Types::RequestOptions)

Returns:



361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
 
# File 'lib/rafflesia/cache.rb', line 361

def workloadProfiles(
  workload: nil,
  request_options: {}
)
  body = {
    'workload' => workload
  }.compact
  response = @client.request(
    method: :post,
    path: '/v1/cache/workload-profiles',
    auth: true,
    body: body,
    request_options: request_options
  )
  result = Rafflesia::EnvelopeServerlessWorkloadProfileListData.new(response.body)
  result.last_response = Rafflesia::Types::ApiResponse.new(http_status: response.code.to_i, http_headers: response.each_header.to_h, request_id: response["x-request-id"])
  result
end