0
# SOAP Server
1

2
Server functionality for hosting SOAP web services on HTTP servers with automatic WSDL generation, request handling, and service method routing.
3

4
## Capabilities
5

6
### Server Creation Functions
7

8
Create SOAP servers on existing HTTP server instances with service implementations and WSDL definitions.
9

10
```typescript { .api }
11
/**
12
 * Create SOAP server with individual parameters
13
 * @param server - HTTP server instance (Node.js http.Server or Express app)
14
 * @param path - URL path where WSDL will be served (e.g., '/wsdl')
15
 * @param services - Service implementation object
16
 * @param wsdl - WSDL content as string or file path
17
 * @param callback - Optional completion callback
18
 * @returns Server instance
19
 */
20
function listen(
21
  server: any,
22
  path: string,
23
  services: IServices,
24
  wsdl: string,
25
  callback?: (err: any, res: any) => void
26
): Server;
27

28
/**
29
 * Create SOAP server with options object
30
 * @param server - HTTP server instance
31
 * @param options - Server configuration options
32
 * @returns Server instance
33
 */
34
function listen(
35
  server: any,
36
  options: IServerOptions
37
): Server;
38
```
39

40
**Usage Examples:**
41

42
```typescript
43
import { listen } from "soap";
44
import * as http from "http";
45

46
// Service implementation
47
const myService = {
48
  MyService: {
49
    MyServiceSoapPort: {
50
      MyFunction: function(args, callback, headers, req) {
51
        console.log('Received:', args);
52
        callback({
53
          name: args.name,
54
          result: `Hello ${args.name}`
55
        });
56
      },
57
      
58
      GetUserInfo: function(args, callback) {
59
        // Simulate database lookup
60
        const user = { id: args.userId, name: 'John Doe' };
61
        callback({ user });
62
      }
63
    }
64
  }
65
};
66

67
// Create HTTP server
68
const server = http.createServer();
69

70
// Attach SOAP service
71
const soapServer = listen(server, '/wsdl', myService, wsdlContent);
72

73
server.listen(8000, () => {
74
  console.log('SOAP server listening on port 8000');
75
  console.log('WSDL available at http://localhost:8000/wsdl?wsdl');
76
});
77
```
78

79
### Server Class
80

81
SOAP server class managing service routing and request processing.
82

83
```typescript { .api }
84
/**
85
 * SOAP Server class for hosting web services
86
 * Extends EventEmitter for request/response monitoring
87
 */
88
class Server extends EventEmitter {
89
  /** URL path where the service is hosted */
90
  path: string | RegExp;
91
  /** Service implementations */
92
  services: IServices;
93
  /** Logging function for server operations */
94
  log: (type: string, data: any, req: any) => any;
95
  /** Function to authorize incoming connections */
96
  authorizeConnection: (req: any, res?: any) => boolean;
97
  /** Function to authenticate security credentials */
98
  authenticate: (security: any, processAuthResult?: (result: boolean) => void, req?: any, obj?: any) => boolean | void | Promise<boolean>;
99
  
100
  constructor(server: any, path: string | RegExp, services: IServices, wsdl: WSDL, options?: IServerOptions);
101
}
102
```
103

104
### Server Events
105

106
Monitor incoming requests and header processing.
107

108
```typescript { .api }
109
/**
110
 * Server events for monitoring SOAP requests
111
 */
112
interface Server extends EventEmitter {
113
  /** Emitted for every received messages */
114
  on(event: 'request', listener: (request: any, methodName: string) => void): this;
115
  /** Emitted when the SOAP Headers are not empty */
116
  on(event: 'headers', listener: (headers: any, methodName: string) => void): this;
117
  /** Emitted before sending SOAP response */
118
  on(event: 'response', listener: (response: any, methodName: string) => void): this;
119
  
120
  emit(event: 'request', request: any, methodName: string): boolean;
121
  emit(event: 'headers', headers: any, methodName: string): boolean;
122
  emit(event: 'response', headers: any, methodName: string): boolean;
123
}
124
```
125

126
**Usage Examples:**
127

128
```typescript
129
soapServer.on('request', (request, methodName) => {
130
  console.log(`SOAP request for method: ${methodName}`);
131
  console.log('Request body:', request.body);
132
});
133

134
soapServer.on('headers', (headers, methodName) => {
135
  console.log(`Headers for ${methodName}:`, headers);
136
});
137

138
soapServer.on('response', (response, methodName) => {
139
  console.log(`Sending response for method: ${methodName}`);
140
  console.log('Response:', response);
141
});
142
```
143

144
### Server Methods
145

146
Manage SOAP headers and server configuration.
147

148
```typescript { .api }
149
/**
150
 * Add SOAP header to server responses
151
 * @param soapHeader - Header object or XML string
152
 * @param name - Header name (optional)
153
 * @param namespace - Header namespace (optional)
154
 * @param xmlns - XML namespace (optional)
155
 * @returns Index of the added header
156
 */
157
addSoapHeader(soapHeader: any, name?: string, namespace?: any, xmlns?: string): number;
158

159
/**
160
 * Modify existing SOAP header at specified index
161
 * @param index - Index of header to modify
162
 * @param soapHeader - New header object or XML string
163
 * @param name - Header name (optional)
164
 * @param namespace - Header namespace (optional)
165
 * @param xmlns - XML namespace (optional)
166
 */
167
changeSoapHeader(index: any, soapHeader: any, name?: any, namespace?: any, xmlns?: any): void;
168

169
/**
170
 * Get array of current SOAP headers
171
 * @returns Array of current headers
172
 */
173
getSoapHeaders(): string[];
174

175
/**
176
 * Clear all SOAP headers
177
 */
178
clearSoapHeaders(): void;
179
```
180

181
**Usage Examples:**
182

183
```typescript
184
// Add custom SOAP headers to responses
185
soapServer.addSoapHeader({
186
  'ns1:ServerInfo': {
187
    'ns1:Version': '1.0',
188
    'ns1:Timestamp': new Date().toISOString()
189
  }
190
});
191

192
// Clear headers when needed
193
soapServer.clearSoapHeaders();
194

195
### Service Implementation Structure
196

197
Define service methods that handle SOAP operations.
198

199
```typescript { .api }
200
/**
201
 * Service structure matching WSDL service/port/operation hierarchy
202
 */
203
interface IServices {
204
  [serviceName: string]: {
205
    [portName: string]: {
206
      [operationName: string]: ISoapServiceMethod;
207
    };
208
  };
209
}
210

211
/**
212
 * SOAP service method handler signature
213
 * @param args - Parsed arguments from SOAP request
214
 * @param callback - Callback to send response (callback(responseObject))
215
 * @param headers - SOAP headers from request  
216
 * @param req - Raw HTTP request object
217
 */
218
interface ISoapServiceMethod {
219
  (
220
    args: any,
221
    callback: (response: any) => void,
222
    headers?: any,
223
    req?: any
224
  ): void;
225
}
226
```
227

228
**Usage Examples:**
229

230
```typescript
231
const calculatorService = {
232
  CalculatorService: {
233
    CalculatorSoapPort: {
234
      Add: function(args, callback) {
235
        const result = args.a + args.b;
236
        callback({ result });
237
      },
238
      
239
      Subtract: function(args, callback) {
240
        const result = args.a - args.b;
241
        callback({ result });
242
      },
243
      
244
      // Method with error handling
245
      Divide: function(args, callback) {
246
        if (args.b === 0) {
247
          const fault = {
248
            Fault: {
249
              faultcode: 'Server',
250
              faultstring: 'Division by zero'
251
            }
252
          };
253
          callback(fault);
254
          return;
255
        }
256
        
257
        const result = args.a / args.b;
258
        callback({ result });
259
      },
260
      
261
      // Method accessing request headers
262
      SecureOperation: function(args, callback, headers, req) {
263
        const authHeader = headers.Authorization;
264
        if (!authHeader) {
265
          callback({
266
            Fault: {
267
              faultcode: 'Client',
268
              faultstring: 'Authorization required'
269
            }
270
          });
271
          return;
272
        }
273
        
274
        callback({ status: 'success' });
275
      }
276
    }
277
  }
278
};
279
```
280

281
## Configuration Types
282

283
### Server Options
284

285
```typescript { .api }
286
interface IServerOptions {
287
  /** URL path for WSDL endpoint */
288
  path: string;
289
  /** Service implementations */
290
  services: IServices;
291
  /** WSDL content or file path */
292
  wsdl: string;
293
  /** Optional completion callback */
294
  callback?: (err: any, res: any) => void;
295
  /** Additional server configuration */
296
  xml?: string;
297
  /** URI path for service operations */
298
  uri?: string;
299
  /** Custom SOAP headers to include in responses */
300
  headers?: any;
301
  /** Enable request logging */
302
  enableLogging?: boolean;
303
}
304
```
305

306
### WSDL Integration
307

308
The server automatically handles WSDL serving and operation routing based on the WSDL definition.
309

310
**WSDL Access:**
311
- WSDL is served at `{serverPath}?wsdl`
312
- Service operations are accessible via POST to the server path
313
- Operation routing is based on SOAPAction header and operation name
314

315
**Example WSDL Structure:**
316

317
```xml
318
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
319
             targetNamespace="http://example.com/calculator"
320
             xmlns:tns="http://example.com/calculator">
321
  
322
  <service name="CalculatorService">
323
    <port name="CalculatorSoapPort" binding="tns:CalculatorBinding">
324
      <soap:address location="http://localhost:8000/calculator"/>
325
    </port>
326
  </service>
327
  
328
  <portType name="CalculatorPortType">
329
    <operation name="Add">
330
      <input message="tns:AddRequest"/>
331
      <output message="tns:AddResponse"/>
332
    </operation>
333
  </portType>
334
  
335
</definitions>
336
```
337

338
The service implementation must match this hierarchy:
339
- Service name: `CalculatorService`  
340
- Port name: `CalculatorSoapPort`
341
- Operation name: `Add`
342

343
## Advanced Server Features
344

345
### SOAP Fault Handling
346

347
Return SOAP faults for error conditions using standard fault structure.
348

349
```typescript { .api }
350
/**
351
 * SOAP fault response structure
352
 */
353
interface ISoapFaultResponse {
354
  Fault: {
355
    /** Fault code (Client, Server, etc.) */
356
    faultcode: string;
357
    /** Human-readable fault description */
358
    faultstring: string;
359
    /** Optional fault actor */
360
    faultactor?: string;
361
    /** Optional detailed fault information */
362
    detail?: any;
363
  };
364
}
365
```
366

367
### Custom Response Headers
368

369
Include custom headers in SOAP responses.
370

371
```typescript
372
// In service method
373
MyMethod: function(args, callback, headers, req) {
374
  // Set custom response headers
375
  req.res.setHeader('X-Custom-Header', 'value');
376
  
377
  callback({ result: 'success' });
378
}
379
```
380

381
### Express.js Integration
382

383
SOAP servers work seamlessly with Express.js applications.
384

385
```typescript
386
import express from 'express';
387
import { listen } from 'soap';
388

389
const app = express();
390

391
// Add SOAP service to Express app
392
const soapServer = listen(app, '/soap', services, wsdl);
393

394
// Regular Express routes can coexist
395
app.get('/health', (req, res) => {
396
  res.json({ status: 'ok' });
397
});
398

399
app.listen(3000);
400
```