#1038

batchWrite() silently ignores policies.batch config — requires policies.batchParentWrite (undocumented)

OpenKuxhaopened 4mo ago

Describe the bug

The API surface implies policies.batch governs all batch operations. However, client.batchWrite() strictly reads policies.batchParentWrite (which maps to the C client's batch_parent_write field), not policies.batch. Setting policies.batch alone results in a silent failure to apply timeouts and retries, falling back to C client defaults.

This causes silent misconfiguration: custom timeouts and retry settings are discarded without error or warning.

To Reproduce

  1. Configure the client with only policies.batch:
const Aerospike = require('aerospike')

const client = await Aerospike.connect({
  hosts: [{ addr: '127.0.0.1', port: 3000 }],
  policies: {
    batch: new Aerospike.BatchPolicy({ totalTimeout: 60000, maxRetries: 2 })
    // batchParentWrite is NOT set
  }
})

const records = [
  {
    type: Aerospike.batchType.BATCH_WRITE,
    key: new Aerospike.Key('test', 'demo', 'key1'),
    ops: [Aerospike.operations.write('value', 1)]
  }
]

// totalTimeout: 60000 is silently ignored here - C client defaults are used instead
await client.batchWrite(records)

console.log('policies.batch.totalTimeout:', client.config.policies.batch.totalTimeout) // 60000
console.log('policies.batchParentWrite:', client.config.policies.batchParentWrite)     // undefined

  1. Observe: The totalTimeout from policies.batch is never applied to batchWrite().

Root cause (confirmed in source)

  • config.cc line 277: policies.batch maps to C's as_config.policies.batch
  • config.cc line 297: policies.batchParentWrite maps to C's as_config.policies.batch_parent_write
  • batch_write_async.cc lines 40-61: p_policy is initialized to NULL (line 40) and only set if an explicit policy object is passed as the second argument (lines 49-56). When p_policy = NULL is passed to aerospike_batch_write_async() (line 61), the C client falls back to the as_config.policies.batch_parent_write field. Since batchParentWrite was never set in the JS config, that field holds C-client defaults - not the custom totalTimeout/maxRetries from policies.batch.

Furthermore, the JSDoc example for Client#batchWrite (lib/client.js ~line 1524) currently displays policies.batch in the config example, directing users to the incorrect configuration slot.

Expected behavior

  1. JSDoc/TypeScript Correction: The documentation for batchWrite() must use batchParentWrite instead of batch to ensure developers configure the correct slot.
  2. Configuration Validation: A runtime warning should be evaluated during the initial Aerospike.connect() phase if policies.batch is set but policies.batchParentWrite is omitted. Evaluating this warning inside batchWrite() directly should be avoided to prevent degrading production throughput on a hot path.

The three policy slots and what they actually control:

Config keyC client fieldUsed by
policies.batchpolicies.batchbatchRead() only
policies.batchWritepolicies.batch_writeper-record write metadata (ttl, gen)
policies.batchParentWritepolicies.batch_parent_writebatchWrite() overall timeout/retry

Versions and Environment

  • Client application OS: Ubuntu 24.04.3 LTS
  • Aerospike Client Version: 6.6.1
  • Aerospike Database Version: latest

Additional context

I have a fix ready for the JSDoc correction and the connection-time validation warning. I can submit a PR if this approach is approved.

Activity

3
Kuxha4mo ago

Note : This is actually a bug i had to spend 1 whole dsy trying to fix I kept seeing why the timeout was not being considerd, and went on a wild goose chase for hours until finally figuring it out that we need to add it explictly

(also AI Note : I have used claude to change the grammar + structure it better. apologies if that is not allowed. rest assured, this is not a random agent commenting on an issue)

juliannguyen44mo ago

Hi @Kuxha, I created a ticket internally to address this

shaimoria-del2mo ago

We also had this exact same issue. @juliannguyen4 is there any progress on that ticket? i don't want to keep this configuration if you guys going to fix it