stinger-ipc 0.11.0.dev1__tar.gz → 0.11.0.dev2__tar.gz

{stinger_ipc-0.11.0.dev1/stinger_ipc.egg-info → stinger_ipc-0.11.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stinger-ipc
-Version: 0.11.0.dev1
+Version: 0.11.0.dev2
 Summary: Tools to create code to do IPC over MQTT
 License: MIT License
         Copyright © 2018-2025 Jacob Brunson.

{stinger_ipc-0.11.0.dev1 → stinger_ipc-0.11.0.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stinger-ipc"
-version = "0.11.0.dev1"
+version = "0.11.0.dev2"
 description = "Tools to create code to do IPC over MQTT"
 readme = "README.md"
 requires-python = ">=3.12"

{stinger_ipc-0.11.0.dev1 → stinger_ipc-0.11.0.dev2/stinger_ipc.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stinger-ipc
-Version: 0.11.0.dev1
+Version: 0.11.0.dev2
 Summary: Tools to create code to do IPC over MQTT
 License: MIT License
         Copyright © 2018-2025 Jacob Brunson.

{stinger_ipc-0.11.0.dev1 → stinger_ipc-0.11.0.dev2}/stingeripc/components.py

@@ -257,6 +257,14 @@ class StingerSpec:
         """True if any payload in the interface is a protobuf message."""
         return any(payload.is_protobuf for payload in self.all_payloads())
 
+    def uses_well_known_protobuf(self) -> bool:
+        """True if any payload is one of protobuf's well-known types.
+
+        Those come from the protobuf runtime rather than from this interface's own
+        .proto files, and some languages need an extra dependency to reach them.
+        """
+        return any(ref.is_well_known for ref in self.all_protobuf_refs())
+
     def uses_json(self) -> bool:
         """True if any payload in the interface is a JSON argument list."""
         return any(not payload.is_protobuf for payload in self.all_payloads())

{stinger_ipc-0.11.0.dev1 → stinger_ipc-0.11.0.dev2}/stingeripc/cpp_symb.py

@@ -444,6 +444,17 @@ class CppProtobufRefSymbols(CppSymbols):
         """The C++ namespace protoc puts this message in, from its protobuf package."""
         return "::".join(p for p in self._ref.package.split(".") if p)
 
+    @property
+    def include(self) -> str:
+        """The ``#include`` argument, brackets and all, for this message's header.
+
+        A well-known type's header ships with libprotobuf and is found on the
+        include path; the interface's own headers protoc wrote into the generated
+        library are quoted and relative to it.
+        """
+        header = self._ref.proto_file.replace(".proto", ".pb.h")
+        return f"<{header}>" if self._ref.is_well_known else f'"proto/{header}"'
+
     @property
     def qualified_name(self) -> str:
         """How generated C++ code names this message, e.g. ``::weather::v1::CurrentConditions``."""

{stinger_ipc-0.11.0.dev1 → stinger_ipc-0.11.0.dev2}/stingeripc/payload.py

@@ -67,6 +67,17 @@ class ProtobufMessageRef(BaseModel):
         """True once the reference has been matched to a message in the .proto sources."""
         return self._descriptor is not None
 
+    @property
+    def is_well_known(self) -> bool:
+        """True for one of protobuf's own well-known types, e.g. ``google.protobuf.Empty``.
+
+        These are declared by the protobuf project rather than by this interface,
+        so they are neither found in the interface's .proto directory nor compiled
+        alongside it: every language's protobuf runtime already ships them, and
+        generated code reaches for that copy instead.
+        """
+        return self.package == "google.protobuf"
+
     @property
     def proto_file(self) -> str:
         """The .proto file that declares this message, relative to the source directory."""

{stinger_ipc-0.11.0.dev1 → stinger_ipc-0.11.0.dev2}/stingeripc/protobuf_compiler.py

@@ -9,11 +9,16 @@ is what the generated code needs in order to import it.
 Matching is done from a descriptor set produced by ``protoc`` rather than by
 parsing ``.proto`` text, so imports, packages and nested messages resolve exactly
 the way the protobuf compiler resolves them.
+
+Protobuf's own well-known types -- ``google.protobuf.Empty`` and its siblings --
+are resolvable without appearing in the interface's sources at all, since they
+are declared by the protobuf project and shipped with every language's runtime.
 """
 
 from __future__ import annotations
 
 import difflib
+import importlib
 import shutil
 import subprocess
 import tempfile
@@ -87,6 +92,49 @@ def _message_names(proto_file: FileDescriptorProto) -> list[tuple[str, Descripto
     return found
 
 
+# The .proto files the protobuf project ships as its "well-known types".  Every
+# protobuf runtime carries them, so a message from one of these resolves without
+# the interface declaring anything, and nothing here is ever copied or compiled
+# into the generated output.  Listed by module rather than discovered, because the
+# set is fixed by the protobuf specification and reading it from the runtime's
+# descriptor pool would only report whichever modules happened to be imported.
+_WELL_KNOWN_MODULES = (
+    "any_pb2",
+    "api_pb2",
+    "duration_pb2",
+    "empty_pb2",
+    "field_mask_pb2",
+    "source_context_pb2",
+    "struct_pb2",
+    "timestamp_pb2",
+    "type_pb2",
+    "wrappers_pb2",
+)
+
+_well_known_index: Optional[dict[str, tuple[str, DescriptorProto]]] = None
+
+
+def well_known_message_index() -> dict[str, tuple[str, DescriptorProto]]:
+    """Fully-qualified name -> (declaring file, descriptor) for the well-known types.
+
+    Read out of the protobuf runtime that stinger itself imports, so the messages
+    match the ones the generated code will use, and no protoc invocation is needed
+    to know they exist.
+    """
+    global _well_known_index
+    if _well_known_index is None:
+        index: dict[str, tuple[str, DescriptorProto]] = {}
+        for module_name in _WELL_KNOWN_MODULES:
+            module = importlib.import_module(f"google.protobuf.{module_name}")
+            file_descriptor = module.DESCRIPTOR
+            file_proto = FileDescriptorProto()
+            file_descriptor.CopyToProto(file_proto)
+            for full_name, descriptor in _message_names(file_proto):
+                index[full_name] = (file_descriptor.name, descriptor)
+        _well_known_index = index
+    return _well_known_index
+
+
 class ProtobufSources:
     """The ``.proto`` files an interface draws its messages from."""
 
@@ -102,6 +150,16 @@ class ProtobufSources:
             raise ProtobufError(f"Protobuf source directory not found: {self.proto_dir}")
         return sorted(self.proto_dir.rglob("*.proto"))
 
+    @property
+    def has_sources(self) -> bool:
+        """True when the directory exists and holds at least one .proto file.
+
+        An interface whose only protobuf payloads are well-known types declares no
+        .proto files of its own, so the absence of sources is not an error until
+        something actually needs to be compiled.
+        """
+        return self.proto_dir.is_dir() and any(self.proto_dir.rglob("*.proto"))
+
     def run(self, *flags: str) -> None:
         """Run protoc over every source file with the given flags."""
         files = self.proto_files
@@ -125,9 +183,10 @@ class ProtobufSources:
         """Fully-qualified message name -> (declaring file, descriptor), compiled once."""
         if self._index is None:
             index: dict[str, tuple[str, DescriptorProto]] = {}
-            for proto_file in self.descriptor_set().file:
-                for full_name, descriptor in _message_names(proto_file):
-                    index[full_name] = (proto_file.name, descriptor)
+            if self.has_sources:
+                for proto_file in self.descriptor_set().file:
+                    for full_name, descriptor in _message_names(proto_file):
+                        index[full_name] = (proto_file.name, descriptor)
             self._index = index
         return self._index
 
@@ -139,16 +198,19 @@ class ProtobufSources:
     def resolve(self, ref: ProtobufMessageRef) -> None:
         """Match a reference to a message in the sources, filling in its descriptor.
 
-        Raises with the closest matching names when the message is not found, since
-        a typo in a fully-qualified name is otherwise tedious to spot.
+        A well-known type is matched against the protobuf runtime instead of the
+        sources, since it is not the interface's to declare.  Otherwise this raises
+        with the closest matching names, since a typo in a fully-qualified name is
+        tedious to spot.
         """
-        index = self._message_index()
+        index = well_known_message_index() if ref.is_well_known else self._message_index()
         found = index.get(ref.full_name)
         if found is None:
-            known = self.message_names
+            known = sorted(index)
             suggestions = difflib.get_close_matches(ref.full_name, known, n=3)
             hint = f"  Did you mean: {', '.join(suggestions)}?" if suggestions else f"  Available messages: {', '.join(known) or '(none)'}"
-            raise ProtobufError(f"Protobuf message '{ref.full_name}' was not found in {self.proto_dir}.{hint}")
+            where = "protobuf's well-known types" if ref.is_well_known else str(self.proto_dir)
+            raise ProtobufError(f"Protobuf message '{ref.full_name}' was not found in {where}.{hint}")
         proto_file, descriptor = found
         ref._proto_file = proto_file
         ref._descriptor = descriptor

{stinger_ipc-0.11.0.dev1 → stinger_ipc-0.11.0.dev2}/stingeripc/python_symb.py

@@ -499,6 +499,16 @@ class PythonProtobufRefSymbols(PythonSymbols):
             stem = stem[: -len(".proto")]
         return f"{stem}_pb2"
 
+    @property
+    def import_statement(self) -> str:
+        """The import that brings this message's module into a generated module.
+
+        A well-known type comes from the installed protobuf runtime; everything
+        else from the bindings protoc wrote beside the generated package.
+        """
+        package = "google.protobuf" if self._ref.is_well_known else ".proto"
+        return f"from {package} import {self.module}"
+
     @property
     def qualified_name(self) -> str:
         """How generated Python code names this message, e.g. ``weather_pb2.CurrentConditions``."""

{stinger_ipc-0.11.0.dev1 → stinger_ipc-0.11.0.dev2}/stingeripc/rust_symb.py

@@ -389,6 +389,26 @@ class RustPayloadSymbols(RustSymbols):
         return self.struct_name
 
 
+# How prost names protobuf's well-known types.  prost never generates code for
+# them: it substitutes a ready-made type, which for most is the `prost-types`
+# struct of the same name, but for `Empty` and the wrapper messages is a plain
+# Rust type instead.  Mirrored here because generated code has to spell the
+# message the same way prost does, and these exceptions are not derivable from
+# the name.  Kept in step with prost-build's `ExternPaths::new`.
+_RUST_WELL_KNOWN_EXCEPTIONS = {
+    "Empty": "()",
+    "BoolValue": "bool",
+    "BytesValue": "::prost::alloc::vec::Vec<u8>",
+    "DoubleValue": "f64",
+    "FloatValue": "f32",
+    "Int32Value": "i32",
+    "Int64Value": "i64",
+    "StringValue": "::prost::alloc::string::String",
+    "UInt32Value": "u32",
+    "UInt64Value": "u64",
+}
+
+
 class RustProtobufRefSymbols(RustSymbols):
     """Rust symbols for a :class:`ProtobufMessageRef`."""
 
@@ -403,12 +423,21 @@ class RustProtobufRefSymbols(RustSymbols):
         prost writes one file per protobuf package with the messages at its top
         level, and those files are included into a single ``proto`` module, so the
         package does not reappear in the Rust path.
+
+        A well-known type is the exception: prost generates nothing for one,
+        substituting the ready-made definition in ``prost-types``.
         """
+        if self._ref.is_well_known:
+            return "::prost_types"
         return "crate::proto"
 
     @property
     def qualified_name(self) -> str:
         """How generated Rust code names this message, fully qualified from the crate root."""
+        if self._ref.is_well_known:
+            substitute = _RUST_WELL_KNOWN_EXCEPTIONS.get(self._ref.message_name)
+            if substitute is not None:
+                return substitute
         return f"{self.module_path}::{self._ref.message_name}"
 
     @property
@@ -416,6 +445,10 @@ class RustProtobufRefSymbols(RustSymbols):
         """How code outside the library names this message.
 
         Examples and integration tests are separate crates, so they import the
-        library's ``proto`` module rather than reaching through ``crate::``.
+        library's ``proto`` module rather than reaching through ``crate::``.  A
+        well-known type is spelled the same way everywhere, since it comes from
+        neither.
         """
+        if self._ref.is_well_known:
+            return self.qualified_name
         return f"proto::{self._ref.message_name}"

{stinger_ipc-0.11.0.dev1 → stinger_ipc-0.11.0.dev2}/stingeripc/schema/0.3/schema.yaml

@@ -259,6 +259,11 @@ $defs:
 
   protobufPayload:
     type: string
+    description: >-
+      The fully-qualified name of a protobuf message carrying this payload, e.g.
+      'weather.v1.Forecast'.  Resolved against the .proto sources configured for
+      the interface, or, for a name in the 'google.protobuf' package, against
+      protobuf's own well-known types, which every protobuf runtime ships.
 
   enumValueDescription:
     type: string

{stinger_ipc-0.11.0.dev1 → stinger_ipc-0.11.0.dev2}/stingeripc/templates/cpp/partials/codec.jinja2

@@ -21,11 +21,12 @@
 {%- endmacro -%}
 
 {#
-    The protoc-generated headers this interface's protobuf payloads come from.
-    Emitted once per .proto file, and nothing at all when no payload is protobuf.
+    The headers this interface's protobuf payloads come from -- protoc-generated
+    for the interface's own messages, shipped with libprotobuf for the well-known
+    types.  Emitted once per header, and nothing at all when no payload is protobuf.
 #}
 {%- macro imports(stinger) -%}
-{%- for proto_file in stinger.protobuf_files() %}
-#include "proto/{{ proto_file | replace(".proto", ".pb.h") }}"
+{%- for include in stinger.protobuf_messages() | map(attribute='cpp.include') | unique | sort %}
+#include {{ include }}
 {%- endfor -%}
 {%- endmacro -%}

{stinger_ipc-0.11.0.dev1 → stinger_ipc-0.11.0.dev2}/stingeripc/templates/python/partials/codec.jinja2

@@ -26,8 +26,8 @@
     all for an interface that uses no protobuf messages.
 #}
 {%- macro imports(stinger) -%}
-{%- for module in stinger.protobuf_messages() | map(attribute='python.module') | unique | sort %}
-from .proto import {{ module }}
+{%- for import_statement in stinger.protobuf_messages() | map(attribute='python.import_statement') | unique | sort %}
+{{ import_statement }}
 {%- endfor -%}
 {%- endmacro -%}
 

{stinger_ipc-0.11.0.dev1 → stinger_ipc-0.11.0.dev2}/stingeripc/templates/rust/Cargo.toml.jinja2

@@ -39,6 +39,9 @@ jsonschema = "0.46" # Only needed because this interface declares JSON schema co
 {%- if stinger.uses_protobuf() %}
 prost = "0.13" # Only needed because this interface carries protobuf payloads.
 {%- endif %}
+{%- if stinger.uses_well_known_protobuf() %}
+prost-types = "0.13" # Only needed because this interface carries protobuf well-known types.
+{%- endif %}
 {%- if stinger.uses_binary() %}
 base64 = "0.22.1" # Only needed because this interface has binary fields.
 {%- endif %}

{stinger_ipc-0.11.0.dev1 → stinger_ipc-0.11.0.dev2}/stingeripc/templates/rust/examples/server_demo.rs.jinja2

@@ -56,7 +56,7 @@ impl {{stinger.name | UpperCamelCase }}MethodHandlers<MqttierClient> for {{sting
     async fn handle_{{method_name|snake_case}}(&self, {%if method.request_payload.is_protobuf%}_payload: {{method.request_payload.protobuf.rust.external_name}}{%else%}{%for arg in method.arg_list%}_{{arg.name|snake_case}}: {{arg.rust.type}}{%if not loop.last%}, {%endif%}{%endfor%}{%endif%}) -> Result<{%if method.response_payload.is_protobuf%}{{method.response_payload.protobuf.rust.external_name}}{%else%}{{method.rust.return_value_type}}{%endif%}, MethodReturnCode> {
         println!("Handling {{method_name}}");
         {%- if method.response_payload.is_protobuf %}
-        Ok({{method.response_payload.protobuf.rust.external_name}}::default())
+        Ok(<{{method.response_payload.protobuf.rust.external_name}} as Default>::default())
         {%- elif method.return_value_type == 'struct'%}
         let rv = {{method.return_value.rust.temp_type}} {
             {%for arg in method.return_value.values-%}

{stinger_ipc-0.11.0.dev1 → stinger_ipc-0.11.0.dev2}/stingeripc/templates/rust/partials/codec.jinja2

@@ -217,7 +217,7 @@ let data = {{ payload.rust.struct_name }} {
 #}
 {%- macro example_payload(payload, arg_list) -%}
 {%- if payload.is_protobuf -%}
-{{ payload.protobuf.rust.external_name }}::default()
+<{{ payload.protobuf.rust.external_name }} as Default>::default()
 {%- else -%}
 {%- for arg in arg_list %}{{ arg.get_random_example_value(lang="rust") }}{% if not loop.last %}, {% endif %}{% endfor -%}
 {%- endif -%}
@@ -229,7 +229,7 @@ let data = {{ payload.rust.struct_name }} {
 #}
 {%- macro example_payload_local(payload, arg_list) -%}
 {%- if payload.is_protobuf -%}
-{{ payload.rust.struct_name }}::default()
+<{{ payload.rust.struct_name }} as Default>::default()
 {%- else -%}
 {%- for arg in arg_list %}{{ arg.get_random_example_value(lang="rust") }}{% if not loop.last %}, {% endif %}{% endfor -%}
 {%- endif -%}
@@ -267,7 +267,7 @@ let data = {{ payload.rust.struct_name }} {
 {# An example value for a property, for demos and generated tests. #}
 {%- macro property_example(prop) -%}
 {%- if prop.payload.is_protobuf -%}
-{{ prop.payload.rust.struct_name }}::default()
+<{{ prop.payload.rust.struct_name }} as Default>::default()
 {%- else -%}
 {{ prop.value.get_random_example_value(lang="rust") }}
 {%- endif -%}
@@ -276,7 +276,7 @@ let data = {{ payload.rust.struct_name }} {
 {# Like `property_example`, but for code outside the library (demos, integration tests). #}
 {%- macro property_example_external(prop) -%}
 {%- if prop.payload.is_protobuf -%}
-{{ prop.payload.protobuf.rust.external_name }}::default()
+<{{ prop.payload.protobuf.rust.external_name }} as Default>::default()
 {%- else -%}
 {{ prop.value.get_random_example_value(lang="rust") }}
 {%- endif -%}

{stinger_ipc-0.11.0.dev1 → stinger_ipc-0.11.0.dev2}/stingeripc/templates/rust/src/server.rs.jinja2

@@ -906,7 +906,7 @@ mod tests {
             Ok(rv)
             {%endif%}
             {%elif method.response_payload.is_protobuf %}
-            Ok({{method.response_payload.rust.struct_name}}::default())
+            Ok(<{{method.response_payload.rust.struct_name}} as Default>::default())
             {%elif method.return_value_type is not false %}
             Ok({{method.return_value.get_random_example_value(lang="rust")}})
             {%else%}
@@ -986,7 +986,7 @@ mod tests {
 
             // Just to get this test working faster, we're copy-pasting test code from payloads.rs to generate example property payloads. 
             {%- if prop.payload.is_protobuf %}
-            let payload = {{prop.payload.rust.struct_name}}::default();
+            let payload = <{{prop.payload.rust.struct_name}} as Default>::default();
             {%- else %}
             let json_str = r#"{ "{{prop.value.name}}": {{prop.value.get_random_example_value(lang="json")}} }"#;
             let payload: {{prop.payload.rust.class_name}} = serde_json::from_str(json_str).unwrap();
@@ -1021,7 +1021,7 @@ mod tests {
 
             // Example values always satisfy any schema constraint declared on the argument,
             // so this payload reaches the channel.
-            let payload = {%if cmd.payload.is_protobuf%}{{cmd.payload.rust.struct_name}}::default(){%else%}{{cmd.rust.payload_struct_name}} {
+            let payload = {%if cmd.payload.is_protobuf%}<{{cmd.payload.rust.struct_name}} as Default>::default(){%else%}{{cmd.rust.payload_struct_name}} {
                 {%-for arg in cmd.arg_list%}
                 {{arg.name|snake_case}}: {{arg.get_random_example_value(lang="rust")}},
                 {%-endfor%}

{stinger_ipc-0.11.0.dev1 → stinger_ipc-0.11.0.dev2}/stingeripc/tools/generic_generator.py

@@ -14,7 +14,7 @@ from stingeripc.loading import parse_yaml_file
 from stevedore import ExtensionManager
 from stingeripc import StingerInterface, __version__, topic_util
 from stingeripc.filtering import filter_by_consumer
-from stingeripc.config import load_config, StingerConfig
+from stingeripc.config import load_config, ProtobufConfig, StingerConfig
 from stingeripc.exceptions import ProtobufError
 from stingeripc.protobuf_compiler import ProtobufSources
 
@@ -68,8 +68,13 @@ def emit_protobuf_bindings(template_dir: Path, outdir: Path, stinger, config_obj
     }
     recipe = tomllib.loads(recipe_path.read_text())
 
-    proto_src = (inname.parent / config_obj.protobuf.path).resolve()
-    sources = ProtobufSources(proto_src, config_obj.protobuf.protoc, python37=config_obj.python.python37)
+    sources = protobuf_sources(config_obj, inname)
+    # An interface whose protobuf payloads are all well-known types has no .proto
+    # files of its own; those messages come from the language's protobuf runtime,
+    # so there is nothing to copy and nothing to compile.
+    if not sources.has_sources:
+        print("🧬    PROTO: no .proto sources to compile (well-known types only)")
+        return
 
     # The .proto files travel with the generated code, so the output is
     # self-contained and can be regenerated for another language later.
@@ -109,6 +114,20 @@ def emit_protobuf_bindings(template_dir: Path, outdir: Path, stinger, config_obj
         target.write_text(content.format(**placeholders))
 
 
+def protobuf_sources(config_obj, inname: Path) -> ProtobufSources:
+    """The .proto sources for an interface, relative to the interface file.
+
+    Resolved relative to the .stinger.yaml so a definition and its .proto files
+    travel together regardless of where the generator is invoked from.  The
+    protobuf configuration is optional: an interface that names only well-known
+    types needs no .proto directory, and the default one simply turns out to be
+    empty.
+    """
+    protobuf_config = config_obj.protobuf or ProtobufConfig()
+    proto_dir = (inname.parent / protobuf_config.path).resolve()
+    return ProtobufSources(proto_dir, protobuf_config.protoc, python37=config_obj.python.python37)
+
+
 def resolve_protobuf_messages(stinger, config_obj, inname: Path) -> None:
     """Match every protobuf message the interface names against the .proto sources.
 
@@ -121,11 +140,8 @@ def resolve_protobuf_messages(stinger, config_obj, inname: Path) -> None:
     if not refs:
         return
 
-    # Relative to the interface file, so a .stinger.yaml and its .proto files
-    # travel together regardless of where the generator is invoked from.
-    proto_dir = (inname.parent / config_obj.protobuf.path).resolve()
-    print(f"🧬 [bold cyan]PROTOS:[/bold cyan] {proto_dir}")
-    sources = ProtobufSources(proto_dir, config_obj.protobuf.protoc, python37=config_obj.python.python37)
+    sources = protobuf_sources(config_obj, inname)
+    print(f"🧬 [bold cyan]PROTOS:[/bold cyan] {sources.proto_dir}")
     sources.resolve_all(refs)
     for ref in stinger.protobuf_messages():
         print(f"🧬    MSG: {ref.full_name} ({ref.proto_file})")

{stinger_ipc-0.11.0.dev1 → stinger_ipc-0.11.0.dev2}/tests/test_protobuf_payloads.py

@@ -15,8 +15,11 @@ from google.protobuf.descriptor_pb2 import FileDescriptorSet
 from stingeripc.components import StingerSpec
 from stingeripc.config import ProtobufConfig, StingerConfig
 from stingeripc.exceptions import InvalidStingerStructure, ProtobufError
+from stingeripc.cpp_symb import CppProtobufRefSymbols
 from stingeripc.payload import PayloadRole, ProtobufMessageRef
-from stingeripc.protobuf_compiler import ProtobufSources, find_protoc
+from stingeripc.protobuf_compiler import ProtobufSources, find_protoc, well_known_message_index
+from stingeripc.python_symb import PythonProtobufRefSymbols
+from stingeripc.rust_symb import RustProtobufRefSymbols
 
 FIXTURES = Path(__file__).parent / "fixtures"
 
@@ -90,6 +93,93 @@ class TestResolution(unittest.TestCase):
         )
 
 
+
+class TestWellKnownTypes(unittest.TestCase):
+    """Protobuf's own types resolve without the interface declaring them."""
+
+    def _resolved(self, full_name: str) -> ProtobufMessageRef:
+        ref = ProtobufMessageRef(full_name=full_name)
+        _sources().resolve(ref)
+        return ref
+
+    def test_recognises_the_google_protobuf_package(self):
+        self.assertTrue(ProtobufMessageRef(full_name="google.protobuf.Empty").is_well_known)
+        self.assertFalse(ProtobufMessageRef(full_name="weather.v1.Forecast").is_well_known)
+        self.assertFalse(
+            ProtobufMessageRef(full_name="google.protobuf.nested.Thing").is_well_known,
+            "only the well-known package itself, not anything beneath it",
+        )
+
+    def test_resolves_without_any_local_sources(self):
+        ref = self._resolved("google.protobuf.Empty")
+        self.assertTrue(ref.is_resolved)
+        self.assertEqual(ref.proto_file, "google/protobuf/empty.proto")
+
+    def test_resolves_with_no_proto_directory_at_all(self):
+        """An interface using only well-known types needs no .proto sources."""
+        sources = ProtobufSources(FIXTURES / "no_such_directory")
+        self.assertFalse(sources.has_sources)
+        ref = ProtobufMessageRef(full_name="google.protobuf.Empty")
+        sources.resolve(ref)
+        self.assertTrue(ref.is_resolved)
+
+    def test_index_covers_the_whole_well_known_set(self):
+        index = well_known_message_index()
+        for name in ("Empty", "Timestamp", "Duration", "Any", "Struct", "FieldMask", "StringValue"):
+            self.assertIn(f"google.protobuf.{name}", index)
+
+    def test_unknown_well_known_type_is_reported_against_the_right_place(self):
+        ref = ProtobufMessageRef(full_name="google.protobuf.Emty")
+        with self.assertRaises(ProtobufError) as caught:
+            _sources().resolve(ref)
+        message = str(caught.exception)
+        self.assertIn("well-known types", message)
+        self.assertIn("google.protobuf.Empty", message, "a near miss is suggested")
+
+    def test_interface_reports_that_it_uses_them(self):
+        spec = _spec({"commands": {"c": {"protobuf": "google.protobuf.Empty"}}})
+        self.assertTrue(spec.uses_protobuf())
+        self.assertTrue(spec.uses_well_known_protobuf())
+
+    def test_interface_of_its_own_messages_only_does_not(self):
+        spec = _spec({"commands": {"c": {"protobuf": "weather.v1.Forecast"}}})
+        self.assertTrue(spec.uses_protobuf())
+        self.assertFalse(spec.uses_well_known_protobuf())
+
+    def test_python_imports_from_the_installed_runtime(self):
+        symbols = PythonProtobufRefSymbols(self._resolved("google.protobuf.Empty"))
+        self.assertEqual(symbols.import_statement, "from google.protobuf import empty_pb2")
+        self.assertEqual(symbols.qualified_name, "empty_pb2.Empty")
+
+    def test_python_imports_the_interfaces_own_messages_from_its_package(self):
+        symbols = PythonProtobufRefSymbols(self._resolved("weather.v1.Forecast"))
+        self.assertEqual(symbols.import_statement, "from .proto import weather_pb2")
+
+    def test_cpp_includes_the_libprotobuf_header(self):
+        symbols = CppProtobufRefSymbols(self._resolved("google.protobuf.Empty"))
+        self.assertEqual(symbols.include, "<google/protobuf/empty.pb.h>")
+        self.assertEqual(symbols.qualified_name, "::google::protobuf::Empty")
+
+    def test_cpp_includes_the_interfaces_own_headers_relatively(self):
+        symbols = CppProtobufRefSymbols(self._resolved("weather.v1.Forecast"))
+        self.assertEqual(symbols.include, '"proto/weather.pb.h"')
+
+    def test_rust_uses_the_substitute_prost_gives_empty(self):
+        symbols = RustProtobufRefSymbols(self._resolved("google.protobuf.Empty"))
+        self.assertEqual(symbols.qualified_name, "()", "prost maps Empty onto the unit type")
+        self.assertEqual(symbols.external_name, "()")
+
+    def test_rust_uses_prost_types_for_the_rest(self):
+        symbols = RustProtobufRefSymbols(self._resolved("google.protobuf.Timestamp"))
+        self.assertEqual(symbols.qualified_name, "::prost_types::Timestamp")
+        self.assertEqual(symbols.external_name, "::prost_types::Timestamp")
+
+    def test_rust_still_reaches_the_interfaces_own_messages_through_the_crate(self):
+        symbols = RustProtobufRefSymbols(self._resolved("weather.v1.Forecast"))
+        self.assertEqual(symbols.qualified_name, "crate::proto::Forecast")
+        self.assertEqual(symbols.external_name, "proto::Forecast")
+
+
 class TestFindProtoc(unittest.TestCase):
     def test_prefers_protoc_on_path(self):
         with mock.patch("shutil.which", side_effect=lambda name: "/usr/bin/protoc" if name == "protoc" else None):