# Sgcwebsockets Core

> Use when writing Delphi or C++Builder code for WebSocket clients and servers with eSeGeCe sgcWebSockets. Covers TsgcWebSocketClient, TsgcWebSocketServer, TsgcWebSocketHTTPServer, the proxy and load balancer servers, the HTTP.sys server, clustering, and the firewall, rate limiter, circuit breaker and API key manager.

- Skill: `esegece-com/sgcwebsockets-core` (Agent Skill, multi-file: 282 files)
- Install (CLI): `npx skillmds@latest add esegece-com/sgcwebsockets-core`
- Raw SKILL.md: https://api.skillmd.com/api/skills/esegece-com/sgcwebsockets-core/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: esegece-com (https://skillmd.com/u/esegece-com)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/esegece-com/sgcwebsockets-core

---


# sgcWebSockets Core

sgcWebSockets Core is the WebSocket client and the WebSocket servers: the pieces
you reach for first. Everything else in the suite either rides on top of these
components or plugs into them.

## When to use this skill

- Open a WebSocket connection from a Delphi or C++Builder application
- Host a WebSocket server, with or without HTTP on the same port
- Serve HTTP and WebSocket together, including static files and REST endpoints
- Put a WebSocket server behind a proxy or a load balancer
- Keep a connection alive across network drops, with heartbeat and watchdog
- Protect a server with an IP firewall, rate limiting, a circuit breaker or API keys
- Run several server nodes as one cluster
- Use the Windows HTTP.sys stack instead of Indy for the server

For a specific subprotocol (MQTT, STOMP, AMQP, WAMP) or an exchange feed, this
is the wrong skill. Load `sgcwebsockets-mq`, `sgcwebsockets-protocols` or
`sgcwebsockets-exchanges` instead. They build on the client documented here.

## Install and uses clause

The library is installed as design-time packages in the IDE, so the components
appear on the palette. Nothing compiles, however, until the right unit is in
your `uses` clause. Every API page in this skill states its `unit:` at the top.

For the client and the servers documented here that unit is `sgcWebSocket`:

```pascal
uses
  sgcWebSocket, sgcWebSocket_Classes, sgcWebSocket_Types;
```

`sgcWebSocket_Classes` gives you `TsgcWSConnection`, which every event hands
you. `sgcWebSocket_Types` gives you the enumerations used by the options.

Components are gated by edition. Check the edition column in
`reference/components-index.md` before relying on one.

## Before you start, ask the developer

If your host offers a structured question tool, for example Claude Code's
`AskUserQuestion`, use it. Otherwise ask in chat before writing code. Getting
these wrong produces code that compiles and then fails at runtime:

1. **Client or server?** They are different components with different options.
2. **TLS?** `TLS := True` also needs a TLS handler decision. On Windows the
   SChannel handler needs no DLLs, OpenSSL needs the DLLs deployed next to the
   executable. Ask which they want before writing the setup.
3. **Which Delphi version and platform?** Some options are version gated, and
   the TLS handler choice differs on Linux, Android and iOS.
4. **Blocking or event driven?** `Connect` blocks until connected or timeout.
   Setting `Active := True` returns immediately and reports through `OnConnect`.
   Most GUI code wants the second.
5. **Does the server also need to serve HTTP?** If yes, use
   `TsgcWebSocketHTTPServer`, not `TsgcWebSocketServer`. Switching later means
   rewriting the setup.

## Components in this skill

| Component | Use it for |
| --- | --- |
| `TsgcWebSocketClient` | The standard client, Indy based, all platforms |
| `TsgcWebSocketClient_WinHTTP` | Windows only client with no Indy dependency, uses the OS stack |
| `TsgcWebSocketServer` | WebSocket only server |
| `TsgcWebSocketHTTPServer` | WebSocket plus HTTP on one port, static files, REST |
| `TsgcWebSocketServer_HTTPAPI` | Server on the Windows HTTP.sys kernel stack |
| `TsgcWebSocketProxyServer` | Terminates and forwards WebSocket traffic |
| `TsgcWebSocketLoadBalancerServer` | Distributes clients across server nodes |
| `TsgcWSCluster` | Runs several nodes as one logical server |
| `TsgcWebSocketFirewall` | IP allow and block lists, CIDR ranges |
| `TsgcWSRateLimiter` | Caps message and connection rates |
| `TsgcWSCircuitBreaker` | Sheds load when a downstream dependency fails |
| `TsgcWSAPIKeyManager` | Issues and validates API keys |
| `TsgcHTTPServer` | Plain HTTP server with no WebSocket upgrade |

## Quickstart, client

```pascal
uses
  sgcWebSocket, sgcWebSocket_Classes;

procedure TForm1.FormCreate(Sender: TObject);
begin
  FClient := TsgcWebSocketClient.Create(Self);
  FClient.Host := 'echo.websocket.org';
  FClient.Port := 443;
  FClient.TLS := True;
  FClient.OnConnect := ClientConnect;
  FClient.OnMessage := ClientMessage;
  FClient.OnDisconnect := ClientDisconnect;
  FClient.OnError := ClientError;
  // returns immediately, OnConnect fires when the handshake completes
  FClient.Active := True;
end;

procedure TForm1.ClientConnect(Connection: TsgcWSConnection);
begin
  FClient.WriteData('hello');
end;

procedure TForm1.ClientMessage(Connection: TsgcWSConnection; const Text: string);
begin
  Memo1.Lines.Add(Text);
end;
```

When you have a full endpoint, `URL` is a write-only shortcut that populates
`Host`, `Port`, `TLS` and the query parameters in one assignment:
`FClient.URL := 'wss://echo.websocket.org/socket?token=abc';`. It is write-only,
so you cannot read it back; keep your own copy if you need the value later.

## Quickstart, server

```pascal
uses
  sgcWebSocket, sgcWebSocket_Classes;

procedure TForm1.FormCreate(Sender: TObject);
begin
  FServer := TsgcWebSocketServer.Create(Self);
  FServer.Port := 5000;
  FServer.OnConnect := ServerConnect;
  FServer.OnMessage := ServerMessage;
  FServer.Active := True;
end;

procedure TForm1.ServerMessage(Connection: TsgcWSConnection; const Text: string);
begin
  // echo back to the sender
  Connection.WriteData(Text);
  // or broadcast to everyone
  FServer.Broadcast(Text);
end;
```

## Surviving a dropped connection

This is the most common support question, so set it up from the start. The
watchdog reconnects, the heartbeat detects a half-open socket that TCP has not
noticed yet. They solve different problems and are usually both wanted:

```pascal
FClient.WatchDog.Enabled := True;
FClient.WatchDog.Interval := 10;   // seconds between reconnect attempts
FClient.WatchDog.Attempts := 0;    // how many times to retry

FClient.HeartBeat.Enabled := True;
FClient.HeartBeat.Interval := 30;  // seconds between pings
FClient.HeartBeat.Timeout := 0;
```

## Things that catch people out

- `Active := True` does not mean connected. Wait for `OnConnect`. Writing in
  the line after setting `Active` usually raises "socket not connected".
- Events arrive on the connection's own thread, not the main thread. Touching
  VCL or FMX controls directly from an event will eventually corrupt the UI.
  Marshal to the main thread with `TThread.Queue` or `Synchronize`.
- `OnMessage` gives you text frames. Binary frames arrive on `OnBinary`, and a
  message split across frames arrives on `OnFragmented` unless you let the
  library reassemble it.
- A server that must also answer plain HTTP requests, serve static files or
  expose REST endpoints needs `TsgcWebSocketHTTPServer`. `TsgcWebSocketServer`
  handles the WebSocket protocol only.

## Routing

- **Find a component**: `reference/components-index.md` lists every component, its `unit`, and its edition, grouped by Reg module.
- **Uses clause**: add the component's `unit:` value (shown on its API page) to your `uses` clause. Nothing compiles without it.
- **API detail**: `reference/api/<Component>.md` has the Properties, Events and Methods, each in both Delphi and C++Builder form.
- **Option / enum / event types**: property and event types link to `reference/types/<TypeName>.md`, which documents the sub-properties of option classes, the values of enums, and the parameter list of event handlers.
- **Examples**: `examples/index.md` is the full demo catalog; `examples/<Component>.md` is a focused, real usage snippet for the most-used components.
- **Concepts**: `concepts/overview.md` (getting started + uses-clause rule) and `concepts/editions-and-features.md` (which components your edition includes).
- **Bundled resources**: `concepts/resources.md` lists the browser-side assets (JavaScript, HTML, CSS) the server components serve or embed, so a browser client works without an external CDN.
- **Version history**: `reference/history.md` lists what changed in each sgcWebSockets release.

## Editions

Components are gated by edition (Professional, Enterprise, All-Access) or by a feature define. Check the edition column in the components index, or `concepts/editions-and-features.md`, before relying on a component.

Only public and published members are documented. Method bodies, private fields and protected members are intentionally not included.