WebSocket4D

A Windows WebSocket client and server library for Delphi and FreePascal.

WebSocket4D provides a Pascal-oriented API for building real-time applications over WebSocket connections. It is designed for Windows and uses Windows WebSocket/HTTP facilities rather than requiring a separate cross-platform networking stack.

• Created by: Shaahin Ashayeri
• Platform: Windows 8 or later
• Languages: Delphi and FreePascal (FPC)
• License: MIT

Project status: This repository contains implementation code and examples, but the current source package has not been verified here with a Delphi or FreePascal compiler. Please compile and test with your target compiler/version before using it in production.

Features

• WebSocket client and server APIs in Pascal.
• Text and binary message support.
• Event-based notifications for connection, disconnection, incoming messages, and errors where exposed by the relevant class.
• Background/asynchronous receiving through StartReceiving.
• Configurable automatic reconnection options on the client.
• Receive-timeout configuration (in seconds) where supported by the client implementation.
• TLS/WSS example and server-side TLS configuration using certificate and private-key PEM files.
• Example projects demonstrating different library capabilities.

The exact available methods and events depend on the public declarations in WebSocket4D.pas. Consult the source and the example that matches your use case.

Requirements

• Windows 8 or later.
• A compatible Delphi version or FreePascal compiler for Windows.
• For TLS examples, OpenSSL command-line tools to create a local test certificate and the Windows certificate store to trust that certificate for the WinHTTP-based client.
• Firewall permissions for the selected server port when connecting from another machine.

Repository layout

WebSocket4D/
├── README.md
├── Source/
│   ├── WebSocket4D.pas              # Main implementation unit
├── Images/
│   └── WebSocket4D-Banner.png
└── Examples/                        # Sample projects for exploring the library

Getting started

1. Clone or download this repository.
2. Open an example project in the IDE appropriate to your compiler, or create a new Windows console project.
3. Add the folder containing WebSocket4D.pas to the project search path, or include the unit directly as shown by the example's uses clause.
4. Compile for Windows.
5. Start the server example first, then run the client and connect to the server URL/port shown by the example.

Minimal client pattern

The following illustrates the general sequence; adapt event signatures and error handling to the exact unit version in your checkout:

var
  Client: TWebSocket4DClient;
begin
  Client := TWebSocket4DClient.Create;
  try
    Client.Connect('ws://127.0.0.1:8080/');
    Client.StartReceiving;
    Client.SendText('Hello from WebSocket4D');
    Readln;
    Client.Close;
  finally
    Client.Free;
  end;
end.

For a long-running application, assign the relevant events before connecting and ensure the client/server is stopped before freeing it. Do not block a GUI thread with Readln; it is used only in console examples.

Examples

Several example projects are included in the repository to help you explore the library's capabilities and understand how to use its API in practice. Review the examples that best match your needs and adapt them to your application.

If you have any questions or need help using WebSocket4D, please open an issue in the GitHub repository. I will be happy to guide you.

TLS / WSS

ws:// is an unencrypted WebSocket connection; wss:// is WebSocket over TLS. The TLS server example uses ConfigureTLS(CertFile, KeyFile) with a PEM certificate and its matching private key. The client relies on Windows trust validation, so a locally self-signed certificate must be explicitly trusted for local testing and must include the correct Subject Alternative Name (SAN) for the hostname/IP used in the URL.

For certificate generation, Windows certificate-store setup, and troubleshooting, consult the README provided alongside the TLS example.

Security warning: the included certificate-generation script creates a self-signed certificate for local development only. Do not use its private key or certificate in production. For production, use a certificate issued by a trusted CA, protect the private key with appropriate filesystem permissions, renew certificates before expiry, and use the actual DNS name in the URL.

Troubleshooting

• Connection refused / timeout: make sure the server is running, the URL and port match, and Windows Firewall permits the connection.
• TLS certificate error: ensure the certificate is trusted in the correct Windows certificate store and that its SAN matches localhost or the IP/DNS name in the URL. Restart the client after importing the certificate.
• Client connects but no events arrive: start receiving with StartReceiving, assign callbacks before connecting, and check whether the server sends messages.
• Send fails after disconnect: check connection state and error callbacks; if using auto-reconnect, only send after a successful connection event.
• Compiler cannot find the unit: add the correct source directory to the project search path and verify that the project is compiling the intended copy of WebSocket4D.pas.

Threading and lifecycle notes

• Treat callbacks as potentially occurring on a worker/background thread unless the implementation explicitly documents otherwise. Synchronize access to UI controls and shared application state.
• Avoid freeing the client or server from inside a callback unless the implementation explicitly supports that lifecycle.
• Stop receiving/server activity and close connections before destroying objects.
• Automatic reconnection does not guarantee that an application-level operation is safe to repeat. Design message handling to tolerate reconnects and duplicate requests.

Contributing and issues

Bug reports should include Windows version, Delphi/FPC version, the exact example used, reproduction steps, and the full compiler/runtime error. Please avoid including production private keys, credentials, or sensitive payloads in issue reports.

Support WebSocket4D

If you find WebSocket4D useful, please consider supporting its continued development with a voluntary cryptocurrency donation.

Your support helps me maintain the library, improve its documentation and examples, fix bugs, and develop new features.

BNB Donations

Network: BNB Smart Chain (BEP-20)

Wallet address: 0xcB3324b1154CCdB9C497BbfeDd277Ed93407E519

Scan the QR code with your wallet app to donate.

Donations are entirely optional. WebSocket4D remains free and open-source.

Thank you for supporting WebSocket4D!

Created by Shaahin Ashayeri

---

WebSocket4D · Delphi + FreePascal · Windows ·