Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

6.9 KB
Raw Blame
from datetime import date
from typing import Optional, cast

from products.warehouse_sources.sources.ably._config import AblySourceConfig
from products.warehouse_sources.sources.ably.ably import (
    ABLY_VERSION_2,
    AblyResumeConfig,
    ably_source,
    validate_credentials as validate_ably_credentials,
)
from products.warehouse_sources.sources.ably.settings import (
    DEFAULT_STATS_UNIT,
    ENDPOINTS,
    INCREMENTAL_FIELDS,
    STATS_UNITS,
)
from products.warehouse_sources.sources.sdk import (
    UNVERSIONED_API_VERSION,
    CanonicalDescriptions,
    DataWarehouseSourceCategory,
    ExternalDataSourceType,
    FieldType,
    ReleaseStatus,
    ResumableSource,
    ResumableSourceManager,
    SourceConfig,
    SourceFieldInputConfig,
    SourceFieldInputConfigType,
    SourceFieldSelectConfig,
    SourceFieldSelectConfigOption,
    SourceInputs,
    SourceRegistry,
    SourceResponse,
    SourceSchema,
    VersionDeprecation,
    build_endpoint_schemas,
    detect,
)


@SourceRegistry.register
class AblySource(ResumableSource[AblySourceConfig, AblyResumeConfig]):
    codebase_detection = detect(
        env=("^ABLY_",),
        script_hosts=("cdn.ably.com",),
        npm=("ably",),
        pypi=("ably",),
        cocoapods=("Ably", "AblyDeltaCodec", "AblyRealtime"),
        composer=("ably/ably-php", "ably/ably-php-laravel"),
        go=(
            "github.com/ably/ably-go",
            "github.com/ably/ably-common",
            "github.com/ably/ably-common-go",
            "github.com/ably/ably-server",
        ),
        maven=("io.ably:ably-java", "io.ably:ably-android"),
        pub=("ably_flutter", "ably", "ably_pubsub_device", "ably_pubsub_device_flutter"),
        rubygems=("ably", "ably-pubsub-core", "ably-pubsub-server", "ably-rest", "msgpack-ably"),
        swiftpm=(
            "github.com/ably/ably-cocoa",
            "github.com/ably/ably-chat-swift",
            "github.com/ably/ably-cocoa-plugin-support",
            "github.com/ably/ably-liveobjects-swift-plugin",
        ),
    )

    lists_tables_without_credentials = True  # static endpoint catalog — safe for public docs
    api_docs_url = "https://ably.com/docs/api/rest-api"

    supported_versions = (UNVERSIONED_API_VERSION, ABLY_VERSION_2)
    default_version = ABLY_VERSION_2
    deprecated_versions = (VersionDeprecation(version=UNVERSIONED_API_VERSION, sunset_at=date(2025, 11, 1)),)

    @property
    def source_type(self) -> ExternalDataSourceType:
        return ExternalDataSourceType.ABLY

    def get_non_retryable_errors(self) -> dict[str, str | None]:
        return {
            "401 Client Error": "Ably rejected your API key. Check that the key is valid and has the capability this table needs.",
            "403 Client Error": "Ably rejected your API key. Check that the key is valid and has the capability this table needs.",
        }

    def get_canonical_descriptions(self) -> CanonicalDescriptions:
        from products.warehouse_sources.sources.ably.canonical_descriptions import CANONICAL_DESCRIPTIONS

        return CANONICAL_DESCRIPTIONS

    def get_schemas(
        self,
        config: AblySourceConfig,
        team_id: int,
        with_counts: bool = False,
        names: list[str] | None = None,
        force_refresh: bool = False,
        api_version: str | None = None,
    ) -> list[SourceSchema]:
        # The endpoint catalog (`/stats`) and its shape are identical across Ably protocol
        # versions, so discovery is version-independent — the pin is consumed at the request layer.
        return build_endpoint_schemas(ENDPOINTS, INCREMENTAL_FIELDS, names)

    def validate_credentials(
        self, config: AblySourceConfig, team_id: int, schema_name: Optional[str] = None, api_version: str | None = None
    ) -> tuple[bool, str | None]:
        # Pre-creation calls pass no pin and resolve to `default_version` (what new rows are
        # stamped with); a pinned source revalidates under its own `X-Ably-Version` header.
        return validate_ably_credentials(config.api_key, self.resolve_api_version(api_version))

    def get_resumable_source_manager(self, inputs: SourceInputs) -> ResumableSourceManager[AblyResumeConfig]:
        return ResumableSourceManager[AblyResumeConfig](inputs, AblyResumeConfig)

    def source_for_pipeline(
        self,
        config: AblySourceConfig,
        resumable_source_manager: ResumableSourceManager[AblyResumeConfig],
        inputs: SourceInputs,
    ) -> SourceResponse:
        return ably_source(
            api_key=config.api_key,
            endpoint=inputs.schema_name,
            unit=config.unit,
            team_id=inputs.team_id,
            job_id=inputs.job_id,
            resumable_source_manager=resumable_source_manager,
            api_version=self.resolve_api_version(inputs.api_version),
            should_use_incremental_field=inputs.should_use_incremental_field,
            db_incremental_field_last_value=inputs.db_incremental_field_last_value
            if inputs.should_use_incremental_field
            else None,
            incremental_field=inputs.incremental_field,
        )

    @property
    def get_source_config(self) -> SourceConfig:
        return SourceConfig(
            name=ExternalDataSourceType.ABLY,
            category=DataWarehouseSourceCategory.ENGINEERING___MONITORING,
            keywords=["realtime", "pubsub", "messaging"],
            label="Ably",
            caption="Enter your Ably app API key, created in the [Ably dashboard](https://ably.com/dashboard). "
            "The key must include both the key ID and secret (`app-id.key-id:key-secret`).\n\n"
            "Each table needs a capability on the key: `stats` for Stats, `channel-metadata` for "
            "Channels and Presence, and `history` for Channel messages. Message history also needs "
            "persistence turned on for the channel, otherwise Ably keeps messages for two minutes.",
            docsUrl="https://posthog.com/docs/cdp/sources/ably",
            iconPath="/static/services/ably.png",
            releaseStatus=ReleaseStatus.GA,
            fields=cast(
                list[FieldType],
                [
                    SourceFieldInputConfig(
                        name="api_key",
                        label="API key",
                        type=SourceFieldInputConfigType.PASSWORD,
                        required=True,
                        placeholder="xVLyHw.XXXXXX:1234567890abcdef1234567890abcdef12345678",
                        secret=True,
                    ),
                    SourceFieldSelectConfig(
                        name="unit",
                        sync_setting=True,
                        label="Stats granularity",
                        required=True,
                        defaultValue=DEFAULT_STATS_UNIT,
                        options=[SourceFieldSelectConfigOption(label=unit.title(), value=unit) for unit in STATS_UNITS],
                    ),
                ],
            ),
        )