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.

7.0 KB
Raw Blame
from typing import Optional, cast

from products.warehouse_sources.sources.linode._config import LinodeSourceConfig
from products.warehouse_sources.sources.linode.linode import (
    LinodeResumeConfig,
    linode_source,
    validate_credentials as validate_linode_credentials,
)
from products.warehouse_sources.sources.linode.settings import ENDPOINTS, LINODE_ENDPOINTS
from products.warehouse_sources.sources.sdk import (
    CanonicalDescriptions,
    DataWarehouseSourceCategory,
    ExternalDataSourceType,
    FieldType,
    ReleaseStatus,
    ResumableSource,
    ResumableSourceManager,
    SourceConfig,
    SourceFieldInputConfig,
    SourceFieldInputConfigType,
    SourceInputs,
    SourceRegistry,
    SourceResponse,
    SourceSchema,
    detect,
)


@SourceRegistry.register
class LinodeSource(ResumableSource[LinodeSourceConfig, LinodeResumeConfig]):
    codebase_detection = detect(
        env=("^LINODE_",),
        npm=("@linode/api-v4",),
        pypi=("linode-api4", "linode-cli"),
        go=(
            "github.com/linode/linodego",
            "github.com/linode/docker-machine-driver-linode",
            "github.com/linode/docker-volume-linode",
            "github.com/linode/karpenter-provider-linode",
            "github.com/linode/linode-blockstorage-csi-driver",
            "github.com/linode/linode-cloud-controller-manager",
            "github.com/linode/linode-cosi-driver",
            "github.com/linode/linode-filestorage-csi-driver",
            "github.com/linode/packer-plugin-linode",
            "github.com/linode/provider-linode",
        ),
    )

    # get_schemas iterates the static ENDPOINTS catalog with no I/O, so the table list is safe to
    # render in public docs without credentials.
    lists_tables_without_credentials = True
    supported_versions = ("v4",)
    default_version = "v4"
    api_docs_url = "https://techdocs.akamai.com/linode-api/reference"

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

    @property
    def get_source_config(self) -> SourceConfig:
        return SourceConfig(
            name=ExternalDataSourceType.LINODE,
            category=DataWarehouseSourceCategory.ENGINEERING___MONITORING,
            label="Linode",
            releaseStatus=ReleaseStatus.BETA,
            caption="""Enter your Linode (Akamai Connected Cloud) personal access token to pull your account data into the PostHog Data warehouse.

Create a personal access token in the [Linode Cloud Manager](https://cloud.linode.com/profile/tokens). Grant **read-only** access to the resources you want to sync:
- Account (invoices, invoice items, payments, network transfer, events, users)
- Linodes
- Volumes
- NodeBalancers
- Kubernetes
- Domains
- Images
- Databases
""",
            iconPath="/static/services/linode.png",
            docsUrl="https://posthog.com/docs/cdp/sources/linode",
            keywords=["cloud", "infrastructure", "hosting", "akamai"],
            fields=cast(
                list[FieldType],
                [
                    SourceFieldInputConfig(
                        name="api_token",
                        label="Personal access token",
                        type=SourceFieldInputConfigType.PASSWORD,
                        required=True,
                        placeholder="",
                        secret=True,
                    ),
                ],
            ),
            # Kept hidden until the sync logic has been exercised against a live account (we could not
            # curl-verify the incremental X-Filter behavior without credentials).
        )

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

        return CANONICAL_DESCRIPTIONS

    def get_non_retryable_errors(self) -> dict[str, str | None]:
        return {
            # A revoked/invalid token surfaces as a requests HTTPError when `_fetch_page` calls
            # `raise_for_status()`. Retrying can never satisfy a credential problem. Match the stable
            # status text and base host, not the per-request path/query.
            "401 Client Error: Unauthorized for url: https://api.linode.com": "Your Linode API token is invalid or has been revoked. Create a new personal access token in the Linode Cloud Manager, then reconnect.",
            "403 Client Error: Forbidden for url: https://api.linode.com": "Your Linode API token is missing the read scopes needed to sync this data. Grant the required read-only access in the Linode Cloud Manager, then reconnect.",
        }

    def get_schemas(
        self,
        config: LinodeSourceConfig,
        team_id: int,
        with_counts: bool = False,
        names: list[str] | None = None,
        force_refresh: bool = False,
        api_version: str | None = None,
    ) -> list[SourceSchema]:
        def _build_schema(endpoint: str) -> SourceSchema:
            endpoint_config = LINODE_ENDPOINTS[endpoint]
            has_incremental = bool(endpoint_config.incremental_fields)
            return SourceSchema(
                name=endpoint,
                # Events are an immutable, append-only audit log — offer append (server-side cursor via
                # X-Filter) but never merge/upsert. Endpoints with no server-side filter are full refresh.
                supports_incremental=has_incremental and not endpoint_config.append_only,
                supports_append=has_incremental,
                incremental_fields=endpoint_config.incremental_fields,
                should_sync_default=endpoint_config.should_sync_default,
            )

        schemas = [_build_schema(endpoint) for endpoint in ENDPOINTS]
        if names is not None:
            names_set = set(names)
            schemas = [s for s in schemas if s.name in names_set]
        return schemas

    def validate_credentials(
        self,
        config: LinodeSourceConfig,
        team_id: int,
        schema_name: Optional[str] = None,
        api_version: str | None = None,
    ) -> tuple[bool, str | None]:
        return validate_linode_credentials(config.api_token)

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

    def source_for_pipeline(
        self,
        config: LinodeSourceConfig,
        resumable_source_manager: ResumableSourceManager[LinodeResumeConfig],
        inputs: SourceInputs,
    ) -> SourceResponse:
        return linode_source(
            api_token=config.api_token,
            endpoint=inputs.schema_name,
            team_id=inputs.team_id,
            job_id=inputs.job_id,
            resumable_source_manager=resumable_source_manager,
            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,
        )