Skip to content
Sarj Sarj Sarj Standards

require-port-for-service

Consider a consumer-owned port when visible service structure suggests a substitution boundary.

SARJ071 Rule source Tests Catalog JSON

Why

A small port can decouple consumers when they genuinely need to substitute a concrete service boundary.

Fix

When a real consumer needs substitution, define a focused consumer-owned Protocol and type that consumer against it; otherwise suppress the advisory instead of adding an unused abstraction.

Examples

Before — flagged Concrete service directly exposes an injected collaborator
app/services/thing_service.py
class ThingService:
    def __init__(self, client: ThingClient) -> None:
        self.client = client


    def read(self, key: str) -> str:
        return self.client.get(key)


    def write(self, key: str, value: str) -> None:
        self.client.put(key, value)




def sync(service: ThingService) -> None:
    service.write("inbox", service.read("outbox"))
After — preferred A visible structural port already describes the service boundary
app/services/thing_service.py
from typing import Protocol




class ThingServicePort(Protocol):
    def read(self, key: str) -> str: ...
    def write(self, key: str, value: str) -> None: ...




class ThingService:
    def __init__(self, client: ThingClient) -> None:
        self.client = client


    def read(self, key: str) -> str:
        return self.client.get(key)


    def write(self, key: str, value: str) -> None:
        self.client.put(key, value)




def sync(service: ThingServicePort) -> None:
    service.write("inbox", service.read("outbox"))
Before — flagged A native collaborator is hidden behind a directly constructed concrete boundary
app/native.py
from typing import Protocol




class Backend(Protocol):
    def read(self) -> str: ...
    def write(self, value: str) -> None: ...




class Coordinator:
    def __init__(self) -> None:
        self.backend: Backend = native_backend()


    def read(self) -> str:
        return self.backend.read()


    def write(self, value: str) -> None:
        self.backend.write(value)




class Consumer:
    def receive(self) -> str:
        return Coordinator().read()


    def send(self, value: str) -> None:
        Coordinator().write(value)
pyproject.toml
[project]
name = "boundary-example"
version = "0.1.0"
After — preferred A typed factory exposes the consumer's public Protocol
app/native.py
from typing import Protocol, final




class Backend(Protocol):
    def read(self) -> str: ...
    def write(self, value: str) -> None: ...




class Operations(Protocol):
    def read(self) -> str: ...
    def write(self, value: str) -> None: ...




@final
class Coordinator:
    def __init__(self) -> None:
        self.backend: Backend = native_backend()


    def read(self) -> str:
        return self.backend.read()


    def write(self, value: str) -> None:
        self.backend.write(value)




def coordinator() -> Operations:
    return Coordinator()




class Consumer:
    def receive(self) -> str:
        return coordinator().read()


    def send(self, value: str) -> None:
        coordinator().write(value)
pyproject.toml
[project]
name = "boundary-example"
version = "0.1.0"