@alt-javascript/camel-lite-component-ftp 1.0.2

package/README.md

@@ -0,0 +1,71 @@
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What
+
+FTP producer and consumer via [`basic-ftp`](https://www.npmjs.com/package/basic-ftp). Producers upload the exchange body to the configured directory; consumers poll a directory and emit one exchange per file found.
+
+## Install
+
+```sh
+npm install camel-lite-component-ftp
+```
+
+## URI Syntax
+
+```
+ftp://host/directory[?username=u&password=p&port=21&passive=true]
+```
+
+| Parameter  | Default | Description |
+|------------|---------|-------------|
+| `username` | *(required)* | FTP account username. |
+| `password` | *(required)* | FTP account password. |
+| `port`     | `21`    | FTP server port. |
+| `passive`  | `true`  | Use passive mode transfers. Set to `false` for active mode. |
+
+## Usage
+
+**Producer — upload exchange body to FTP directory:**
+
+```js
+import { CamelContext } from 'camel-lite-core';
+import { FtpComponent } from 'camel-lite-component-ftp';
+
+const context = new CamelContext();
+context.addComponent('ftp', new FtpComponent());
+
+context.addRoutes({
+  configure(ctx) {
+    ctx.from('direct:upload')
+      .to('ftp://ftp.example.com/uploads?username=user&password=secret');
+  }
+});
+
+await context.start();
+
+const template = context.createProducerTemplate();
+await template.send('direct:upload', ex => {
+  ex.in.body = 'file content here';
+  ex.in.setHeader('CamelFileName', 'report.txt');
+});
+
+await context.stop();
+```
+
+**Consumer — poll an FTP directory:**
+
+```js
+context.addRoutes({
+  configure(ctx) {
+    ctx.from('ftp://ftp.example.com/inbox?username=user&password=secret')
+      .process(exchange => {
+        console.log('Downloaded:', exchange.in.getHeader('CamelFileName'));
+        console.log('Content:', exchange.in.body);
+      });
+  }
+});
+```
+
+## See Also
+
+[camel-lite — root README](../../README.md)

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@alt-javascript/camel-lite-component-ftp",
+  "version": "1.0.2",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "dependencies": {
+    "basic-ftp": "^5.0.0",
+    "@alt-javascript/logger": "^3.0.7",
+    "@alt-javascript/config": "^3.0.7",
+    "@alt-javascript/common": "^3.0.7",
+    "@alt-javascript/camel-lite-core": "1.0.2"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alt-javascript/camel-lite"
+  },
+  "author": "Craig Parravicini",
+  "contributors": [
+    "Claude (Anthropic)",
+    "Apache Camel — design inspiration and pattern source"
+  ],
+  "keywords": [
+    "alt-javascript",
+    "camel",
+    "camel-lite",
+    "eai",
+    "eip",
+    "integration",
+    "ftp",
+    "sftp",
+    "file-transfer",
+    "component"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/src/FtpClientFactory.js

@@ -0,0 +1,11 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const basicFtp = require('basic-ftp');
+
+/**
+ * ESM/CJS bridge for basic-ftp.
+ * This is the single point where CJS is loaded — keeps the rest of the package pure ESM.
+ */
+export function createFtpClient() {
+  return new basicFtp.Client();
+}

package/src/FtpComponent.js

@@ -0,0 +1,18 @@
+import { Component } from '@alt-javascript/camel-lite-core';
+import FtpEndpoint from './FtpEndpoint.js';
+
+class FtpComponent extends Component {
+  #endpoints = new Map();
+
+  createEndpoint(uri, remaining, parameters, context) {
+    if (this.#endpoints.has(uri)) {
+      return this.#endpoints.get(uri);
+    }
+    const endpoint = new FtpEndpoint(uri, remaining, parameters, context);
+    this.#endpoints.set(uri, endpoint);
+    return endpoint;
+  }
+}
+
+export { FtpComponent };
+export default FtpComponent;

package/src/FtpConsumer.js

@@ -0,0 +1,87 @@
+import { Consumer, Exchange } from '@alt-javascript/camel-lite-core';
+import { LoggerFactory } from '@alt-javascript/logger';
+import { Writable } from 'node:stream';
+
+const log = LoggerFactory.getLogger('@alt-javascript/camel-lite/FtpConsumer');
+
+class FtpConsumer extends Consumer {
+  #uri;
+  #context;
+  #host;
+  #port;
+  #user;
+  #password;
+  #remotePath;
+  #clientFactory;
+
+  constructor(uri, context, host, port, user, password, remotePath, clientFactory) {
+    super();
+    this.#uri = uri;
+    this.#context = context;
+    this.#host = host;
+    this.#port = port;
+    this.#user = user;
+    this.#password = password;
+    this.#remotePath = remotePath;
+    this.#clientFactory = clientFactory;
+  }
+
+  get uri() { return this.#uri; }
+
+  async start() {
+    this.#context.registerConsumer(this.#uri, this);
+    log.info(`FTP consumer started: ${this.#host}${this.#remotePath}`);
+  }
+
+  async stop() {
+    this.#context.registerConsumer(this.#uri, null);
+    log.info(`FTP consumer stopped: ${this.#host}${this.#remotePath}`);
+  }
+
+  /**
+   * One-shot poll: list remote directory, download each file into an Exchange.
+   * Returns an array of Exchange objects, one per remote file.
+   */
+  async poll() {
+    const client = this.#clientFactory();
+    try {
+      await client.access({
+        host: this.#host,
+        port: this.#port,
+        user: this.#user,
+        password: this.#password,
+        secure: false,
+      });
+      log.info(`FTP poll connected: ${this.#host}${this.#remotePath}`);
+
+      const list = await client.list(this.#remotePath);
+      const files = list.filter(item => item.isFile);
+      log.debug(`FTP poll found ${files.length} files in ${this.#remotePath}`);
+
+      const exchanges = [];
+      for (const file of files) {
+        const remoteName = this.#remotePath.replace(/\/$/, '') + '/' + file.name;
+        const chunks = [];
+        const writable = new Writable({
+          write(chunk, _, cb) { chunks.push(chunk); cb(); },
+        });
+        await client.downloadTo(writable, remoteName);
+        log.debug(`FTP downloaded: ${remoteName}`);
+
+        const exchange = new Exchange();
+        exchange.in.body = Buffer.concat(chunks).toString('utf8');
+        exchange.in.setHeader('CamelFileName', file.name);
+        exchange.in.setHeader('CamelFtpRemotePath', remoteName);
+        exchanges.push(exchange);
+      }
+
+      return exchanges;
+    } finally {
+      client.close();
+      log.info(`FTP poll disconnected: ${this.#host}`);
+    }
+  }
+}
+
+export { FtpConsumer };
+export default FtpConsumer;

package/src/FtpEndpoint.js

@@ -0,0 +1,73 @@
+import { Endpoint } from '@alt-javascript/camel-lite-core';
+import FtpProducer from './FtpProducer.js';
+import FtpConsumer from './FtpConsumer.js';
+import { createFtpClient } from './FtpClientFactory.js';
+
+class FtpEndpoint extends Endpoint {
+  #uri;
+  #host;
+  #port;
+  #user;
+  #password;
+  #remotePath;
+  #binary;
+  #context;
+
+  constructor(uri, remaining, parameters, context) {
+    super();
+    this.#uri = uri;
+    this.#context = context;
+
+    // FTP URIs: ftp://user:pass@host:21/remote/path
+    // The raw uri from CamelContext has scheme 'ftp', so we reconstruct a URL:
+    // 'ftp:user:pass@host:21/path' → need to rebuild as 'ftp://user:pass@host:21/path'
+    // Use URL class — it handles authority (user:pass@host:port) correctly.
+    // remaining = everything after 'ftp:' stripped of leading '//'
+    let fullUri = uri;
+    if (!fullUri.startsWith('ftp://') && !fullUri.startsWith('ftps://')) {
+      // Camel-style: ftp:host/path or ftp:user:pass@host:21/path
+      fullUri = fullUri.replace(/^ftp:/, 'ftp://');
+    }
+
+    try {
+      const parsed = new URL(fullUri);
+      this.#host = parsed.hostname || 'localhost';
+      this.#port = parseInt(parsed.port || '21', 10);
+      this.#user = decodeURIComponent(parsed.username || 'anonymous');
+      this.#password = decodeURIComponent(parsed.password || '');
+      this.#remotePath = parsed.pathname || '/';
+    } catch {
+      // Fallback for unparseable URIs
+      this.#host = 'localhost';
+      this.#port = 21;
+      this.#user = 'anonymous';
+      this.#password = '';
+      this.#remotePath = '/' + (remaining || '');
+    }
+
+    const params = parameters instanceof URLSearchParams
+      ? parameters
+      : new URLSearchParams(typeof parameters === 'string' ? parameters : '');
+
+    this.#binary = params.get('binary') === 'true';
+  }
+
+  get uri() { return this.#uri; }
+  get host() { return this.#host; }
+  get port() { return this.#port; }
+  get user() { return this.#user; }
+  get password() { return this.#password; }
+  get remotePath() { return this.#remotePath; }
+  get binary() { return this.#binary; }
+
+  createProducer(clientFactory = createFtpClient) {
+    return new FtpProducer(this.#host, this.#port, this.#user, this.#password, this.#remotePath, clientFactory);
+  }
+
+  createConsumer(pipeline, clientFactory = createFtpClient) {
+    return new FtpConsumer(this.#uri, this.#context, this.#host, this.#port, this.#user, this.#password, this.#remotePath, clientFactory);
+  }
+}
+
+export { FtpEndpoint };
+export default FtpEndpoint;

package/src/FtpProducer.js

@@ -0,0 +1,61 @@
+import { Producer } from '@alt-javascript/camel-lite-core';
+import { LoggerFactory } from '@alt-javascript/logger';
+import { Readable } from 'node:stream';
+
+const log = LoggerFactory.getLogger('@alt-javascript/camel-lite/FtpProducer');
+
+class FtpProducer extends Producer {
+  #host;
+  #port;
+  #user;
+  #password;
+  #remotePath;
+  #clientFactory;
+
+  constructor(host, port, user, password, remotePath, clientFactory) {
+    super();
+    this.#host = host;
+    this.#port = port;
+    this.#user = user;
+    this.#password = password;
+    this.#remotePath = remotePath;
+    this.#clientFactory = clientFactory;
+  }
+
+  get host() { return this.#host; }
+  get remotePath() { return this.#remotePath; }
+
+  async send(exchange) {
+    const client = this.#clientFactory();
+    try {
+      await client.access({
+        host: this.#host,
+        port: this.#port,
+        user: this.#user,
+        password: this.#password,
+        secure: false,
+      });
+      log.info(`FTP connected: ${this.#host}:${this.#port}`);
+
+      const body = exchange.in.body ?? '';
+      const content = typeof body === 'string' ? body : JSON.stringify(body);
+      const stream = Readable.from([content]);
+
+      // File name: CamelFileName header > remotePath (treated as full remote path)
+      const remoteName = exchange.in.getHeader('CamelFtpRemotePath')
+        ?? exchange.in.getHeader('CamelFileName')
+        ?? this.#remotePath;
+
+      await client.uploadFrom(stream, remoteName);
+      log.debug(`FTP uploaded: ${remoteName}`);
+
+      exchange.out.setHeader('CamelFtpRemotePath', remoteName);
+    } finally {
+      client.close();
+      log.info(`FTP disconnected: ${this.#host}`);
+    }
+  }
+}
+
+export { FtpProducer };
+export default FtpProducer;

package/src/index.js

@@ -0,0 +1,8 @@
+export { FtpComponent } from './FtpComponent.js';
+export { FtpEndpoint } from './FtpEndpoint.js';
+export { FtpProducer } from './FtpProducer.js';
+export { FtpConsumer } from './FtpConsumer.js';
+export { createFtpClient } from './FtpClientFactory.js';
+
+import FtpComponent from './FtpComponent.js';
+export default FtpComponent;

package/test/ftp.test.js

@@ -0,0 +1,204 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { Writable } from 'node:stream';
+import { CamelContext, Exchange, Component } from '@alt-javascript/camel-lite-core';
+import { FtpComponent, FtpEndpoint, FtpProducer, FtpConsumer } from '@alt-javascript/camel-lite-component-ftp';
+
+// Mock FtpClient — records calls, no network activity
+class MockFtpClient {
+  calls = [];
+  uploaded = {};
+  // Files available for listing/downloading
+  remoteFiles = [
+    { name: 'alpha.txt', isFile: true, size: 10 },
+    { name: 'beta.txt', isFile: true, size: 8 },
+  ];
+  fileContents = {
+    '/remote/alpha.txt': 'content-alpha',
+    '/remote/beta.txt': 'content-beta',
+  };
+
+  async access(opts) {
+    this.calls.push(['access', opts]);
+  }
+
+  async uploadFrom(stream, remotePath) {
+    const chunks = [];
+    for await (const chunk of stream) chunks.push(Buffer.from(chunk));
+    this.uploaded[remotePath] = Buffer.concat(chunks).toString('utf8');
+    this.calls.push(['uploadFrom', remotePath]);
+  }
+
+  async list(remotePath) {
+    this.calls.push(['list', remotePath]);
+    return this.remoteFiles;
+  }
+
+  async downloadTo(writable, remotePath) {
+    const content = this.fileContents[remotePath] ?? 'default-content';
+    writable.write(Buffer.from(content));
+    writable.end();
+    this.calls.push(['downloadTo', remotePath]);
+    // Wait for writable to finish
+    await new Promise(r => writable.on('finish', r));
+  }
+
+  close() {
+    this.calls.push(['close']);
+  }
+}
+
+function makeMockFactory(mockClient) {
+  return () => mockClient;
+}
+
+describe('FtpProducer', () => {
+  it('send() calls access, uploadFrom, close on the client', async () => {
+    const mock = new MockFtpClient();
+    const producer = new FtpProducer('localhost', 21, 'user', 'pass', '/remote/out.txt', makeMockFactory(mock));
+    const exchange = new Exchange();
+    exchange.in.body = 'hello ftp';
+
+    await producer.send(exchange);
+
+    assert.ok(mock.calls.some(c => c[0] === 'access'));
+    assert.ok(mock.calls.some(c => c[0] === 'uploadFrom'));
+    assert.ok(mock.calls.some(c => c[0] === 'close'));
+    assert.equal(mock.uploaded['/remote/out.txt'], 'hello ftp');
+    assert.equal(exchange.out.getHeader('CamelFtpRemotePath'), '/remote/out.txt');
+  });
+
+  it('send() serialises non-string body as JSON', async () => {
+    const mock = new MockFtpClient();
+    const producer = new FtpProducer('localhost', 21, 'user', 'pass', '/remote/data.json', makeMockFactory(mock));
+    const exchange = new Exchange();
+    exchange.in.body = { key: 'value' };
+
+    await producer.send(exchange);
+
+    assert.deepEqual(JSON.parse(mock.uploaded['/remote/data.json']), { key: 'value' });
+  });
+
+  it('send() uses CamelFileName header as remote path when set', async () => {
+    const mock = new MockFtpClient();
+    const producer = new FtpProducer('localhost', 21, 'user', 'pass', '/default.txt', makeMockFactory(mock));
+    const exchange = new Exchange();
+    exchange.in.body = 'named';
+    exchange.in.setHeader('CamelFileName', '/remote/named.txt');
+
+    await producer.send(exchange);
+
+    assert.ok('/remote/named.txt' in mock.uploaded);
+    assert.equal(mock.uploaded['/remote/named.txt'], 'named');
+  });
+
+  it('send() closes client even when upload fails', async () => {
+    const mock = new MockFtpClient();
+    mock.uploadFrom = async () => { throw new Error('upload failed'); };
+
+    const producer = new FtpProducer('localhost', 21, 'user', 'pass', '/remote/fail.txt', makeMockFactory(mock));
+    const exchange = new Exchange();
+    exchange.in.body = 'data';
+
+    await assert.rejects(() => producer.send(exchange), { message: 'upload failed' });
+    assert.ok(mock.calls.some(c => c[0] === 'close'), 'close should be called even on error');
+  });
+});
+
+describe('FtpConsumer', () => {
+  it('poll() returns one exchange per remote file with correct body', async () => {
+    const mock = new MockFtpClient();
+    const ctx = new CamelContext();
+    const consumer = new FtpConsumer(
+      'ftp://localhost/remote', ctx,
+      'localhost', 21, 'user', 'pass', '/remote',
+      makeMockFactory(mock)
+    );
+    await consumer.start();
+
+    const exchanges = await consumer.poll();
+
+    assert.equal(exchanges.length, 2);
+    const bodies = exchanges.map(e => e.in.body).sort();
+    assert.deepEqual(bodies, ['content-alpha', 'content-beta']);
+    assert.ok(mock.calls.some(c => c[0] === 'list'));
+    assert.ok(mock.calls.some(c => c[0] === 'downloadTo'));
+    assert.ok(mock.calls.some(c => c[0] === 'close'));
+
+    await consumer.stop();
+  });
+
+  it('poll() sets CamelFileName header on each exchange', async () => {
+    const mock = new MockFtpClient();
+    const ctx = new CamelContext();
+    const consumer = new FtpConsumer(
+      'ftp://localhost/remote', ctx,
+      'localhost', 21, 'user', 'pass', '/remote',
+      makeMockFactory(mock)
+    );
+    await consumer.start();
+
+    const exchanges = await consumer.poll();
+    const names = exchanges.map(e => e.in.getHeader('CamelFileName')).sort();
+    assert.deepEqual(names, ['alpha.txt', 'beta.txt']);
+
+    await consumer.stop();
+  });
+
+  it('start() registers consumer with context; stop() deregisters', async () => {
+    const mock = new MockFtpClient();
+    const ctx = new CamelContext();
+    const consumer = new FtpConsumer(
+      'ftp://localhost/remote', ctx,
+      'localhost', 21, 'user', 'pass', '/remote',
+      makeMockFactory(mock)
+    );
+
+    await consumer.start();
+    assert.strictEqual(ctx.getConsumer('ftp://localhost/remote'), consumer);
+
+    await consumer.stop();
+    assert.ok(!ctx.getConsumer('ftp://localhost/remote'));
+  });
+});
+
+describe('FtpEndpoint', () => {
+  it('parses ftp:// URI: host, port, user, password, remotePath', () => {
+    const ctx = new CamelContext();
+    const ep = new FtpEndpoint(
+      'ftp://myuser:mypass@ftphost.example.com:2121/uploads',
+      'uploads',
+      new URLSearchParams(),
+      ctx
+    );
+    assert.equal(ep.host, 'ftphost.example.com');
+    assert.equal(ep.port, 2121);
+    assert.equal(ep.user, 'myuser');
+    assert.equal(ep.password, 'mypass');
+    assert.equal(ep.remotePath, '/uploads');
+  });
+
+  it('defaults port to 21 when not specified', () => {
+    const ctx = new CamelContext();
+    const ep = new FtpEndpoint(
+      'ftp://host/path',
+      'path',
+      new URLSearchParams(),
+      ctx
+    );
+    assert.equal(ep.port, 21);
+  });
+});
+
+describe('cross-package import integration', () => {
+  it('FtpComponent is a subclass of Component', () => {
+    assert.ok(new FtpComponent() instanceof Component);
+  });
+
+  it('FtpComponent.createEndpoint returns FtpEndpoint', () => {
+    const ctx = new CamelContext();
+    const comp = new FtpComponent();
+    const ep = comp.createEndpoint('ftp://localhost/test', 'test', new URLSearchParams(), ctx);
+    assert.ok(ep instanceof FtpEndpoint);
+  });
+});