## Restrictions

- Start Date: 2022-10-09
- RFC PR: [rust-lang/rfcs#3323](https://github.com/rust-lang/rfcs/pull/3323)
- Rust Issue: [rust-lang/rust#105077](https://github.com/rust-lang/rust/issues/105077)

## Summary

You can write `pub impl(crate) trait Foo {}`, which limits the ability to implement the trait to the
crate it is defined in. Similarly, you can write `pub struct Foo(pub mut(crate) u8);` and
`pub struct Foo { pub mut(crate) foo: u8 }`, which limits the ability to mutate the `u8` to `crate`.
Outside of the declared scope, implementing the trait or mutating the field is not allowed. If no
restriction is specified, the ability to implement or mutate is uninhibited.

## Motivation

Currently, a trait being visible (and nameable) in a given location implies that you are able to
implement it. However, this does not mean that you want anyone to implement it. It is reasonable to
want a trait to only be implemented by certain types for a variety of reasons. This is commonly
referred to as a "sealed trait", and is frequently simulated by using a public trait in a private or
restricted module.

Similarly, a field being visible currently implies that you are able to mutate it. Just as with
traits being able to be implemented anywhere, this is not always what is wanted. The semantic
correctness of a field may depend on the value of other fields, for example. This means that making
fields public, while acceptable for read access, is not acceptable for write access. Limiting the
ability to mutate a field to a certain scope is desirable in these situations, while still allowing
read access everywhere else.

## Guide-level explanation

**Restrictions** limit what you are allowed to do with a type. In this sense, visibility is a
restriction! The compiler stops you from using a private type, after all. `#[non_exhaustive]` is
also a restriction, as it requires you to have a wildcard arm in a `match` expression. Both of these
are used on a daily basis by countless Rust programmers.

Restrictions are a powerful tool because the compiler stops you from doing something you are not
allowed to do. If you violate a restriction by using unsafe trickery, such as transmuting a type,
the resulting code is _unsound_.

So why do we need restrictions? In fact, they are incredibly important. Those that have been around
a while will remember a time before `#[non_exhaustive]`. Standard practice at that point in time was
to include a `#[doc(hidden)] __NonExhaustive` variant on `enum`s and a private `non_exhaustive: ()`
field on structs. There are two problems with this approach. First, the variant or field exists!
Yes, that is obvious, but it is worth noting that the user can still match exhaustively. Second, the
dummy variant has to be handled even within the crate that defined it. With the `#[non_exhaustive]`
restriction, this is not the case.

### `impl`-restricted traits

It is very common for a library to want to have a trait that exists _but_ only have it be
implemented for the types they want. It is so common, in fact, that
[there are official guidelines][sealed traits] on how to do this! The pattern is typically referred
to as a "sealed trait". Here is a modified example from the guidelines:

[sealed traits]: https://rust-lang.github.io/api-guidelines/future-proofing.html#sealed-traits-protect-against-downstream-implementations-c-sealed

```rust
/// This trait is sealed and cannot be implemented for types outside this crate.
pub trait Foo: private::Sealed {
    // Methods that the user is allowed to call.
    fn bar();
}

// Implement for some types.
impl Foo for usize {
    fn bar() {}
}

mod private {
    pub trait Sealed {}

    // Implement for those same types, but no others.
    impl Sealed for usize {}
}
```

That is a fair amount of code to say "you cannot implement `Foo`"! This works because it is
permitted to have a public item (`Sealed`) in a private module (`private`). More specifically,
`Sealed` is public, but users in another crate are unable to name the trait. This effectively makes
the trait private, assuming it is not used in other manners. It would be far nicer if you could just
write:

```rust
pub impl(crate) trait Foo {
    fn bar();
}

impl Foo for usize {
    fn bar() {}
}
```

Note that there is neither a `Sealed` trait nor a `private` module here. The ability to implement
`Foo` is restricted by the compiler. It knows this because we used `impl(crate)` — the new syntax
introduced here. Just as `pub` accepts a module path, `impl` does the same. This means that
`impl(super)` and `impl(in path::to::module)` are also valid. Using the `impl` keyword in this
position is a natural extension of the existing visibility syntax. The example above would restrict
the ability to implement the trait to the defining crate. If we used `impl(super)` instead, it would
be restricted to the parent module. If we used `impl(in path::to::module)`, it would be restricted
to the specified module. Any attempt to implement the trait outside of these modules will error. For
example, this code:

```rust
pub mod foo {
    pub mod bar {
        pub(crate) impl(super) trait Foo {}
    }

    // Okay to implement `Foo` here.
    impl bar::Foo for i8 {}
}

impl foo::bar::Foo for u8 {} // Uh oh! We cannot implement `Foo` here.
```

could result in the following error:

```text
error: trait cannot be implemented outside `foo`
  --> $DIR/impl-restriction.rs:13:1
   |
LL |         pub(crate) impl(super) trait Foo {}
   |                    ----------- trait restricted here
...
LL | impl foo::bar::Foo for u8 {}
   | ^^^^^^^^^^^^^^^^^^^^^^^^^

error: aborting due to previous error
```

There are benefits to having this restriction built into the language. First, it expresses the
intent of the author more clearly. Documentation can automatically show that the implementation is
restricted, and the compiler can emit better diagnostics when someone tries to implement `Foo`.
Another benefit is that it is no longer possible to accidentally implement `Sealed` for a type but
not `Foo`. This is a very easy mistake to make, and it is difficult to notice. With the new syntax,
you will only have one trait to worry about.

### `mut`-restricted fields

Have you ever wanted to have read-only fields in Rust? C++, C#, Java, TypeScript, Kotlin, and Swift
all have them in some form or another! In Rust, it is feasible to go one step further and have
fields that are only mutable within a certain module. Said another way, you can mutate it but other
people cannot. This is useful for a number of reasons. For example, you may have a `struct` whose
values are always semantically in a given range. This occurs in `time`:

```rust
pub struct Time {
    hour: u8,
    minute: u8,
    second: u8,
    nanosecond: u32,
}
```

The author of `time` would love to have these fields public. However, they do not want users to be
able to change the values, as that would violate the invariants of the type. As a result they
currently have to keep the fields private and write "getter" methods. What if, instead, they could
add `mut(crate)` to a field, just like `pub(crate)`? This would allow them to write:

```rust
pub struct Time {
    pub mut(crate) hour: u8,
    pub mut(crate) minute: u8,
    pub mut(crate) second: u8,
    pub mut(crate) nanosecond: u32,
}
```

This would mean that the fields are mutable within `time`, but not outside. This avoids the need to
write getters for fields that already exist. While for a type like `Time` this is not a big deal,
having access to fields directly instead of through getters can help with borrow checking. This is
because the compiler is smart enough to know that field accesses cannot overlap, but it does not
know this solely from the function signature of getters.

While there is the [`readonly` crate], this approach has its drawbacks. Namely, the type cannot
implement `Deref`: it already does because of this macro. It is not possible to have only some
fields be read-only: `Deref` is all-or-nothing. It is not possible to make the fields mutable only
within a certain module: `Deref` is a trait that cannot be implemented only in certain locations.
Furthermore, `readonly` does not in any way help with borrow checking. While useful in some
situations, it is by no means a complete solution.

[`readonly` crate]: https://crates.io/crates/readonly

#### Where does a mutation occur?

There is one major question: what even counts as a mutation? This is not as straightforward as you
might think. If you write

```rust
let mut x = 5;
let y = &mut x;
*y = 6;
```

It is without question that a mutation occurs. But where? Does it occur on the second or third line?
In this example, it would not matter, but it is easy to imagine passing a mutable reference to a
function that then mutates the value. There, it is not clear where the mutation occurs. The answer
is that the mutation occurs on the line where the reference is taken. This is the choice that makes
the most sense from the perspective of the user.

```rust
fn foo<T>(x: &mut T, value: T) {
    if random() {
        *x = value;
    }
}

let mut x = 5;
foo(&mut x, 6);
```

Here, `x` is mutably borrowed on the final line, but the value is changed in memory inside the `if`
block. You might say, logically, that the mutation occurs inside the `if` block. But if we use this
definition, then we could not know about the mutation until after monomorphization. Errors generated
post-monomorphization are generally frowned upon, as it happens quite late in the compilation
process. But consider this: what if `x` is not actually mutated within the body of `foo`? Now we
have a window into what actually happens inside the function, and it is something that is not stated
in the function signature. Not great. In this specific example, it is not even deterministic!
Because of this, it is quite literally impossible to know whether `x` is actually mutated inside a
given function. As a result we have no choice: the error _must_ be generated at the point where the
reference is taken.

Okay, we solved that problem. We know that the mutable use happens on the final line. But what about
this?

```rust
let x = Cell::new(5);
x.set(6);
```

Rust has [interior mutability], which is what we are using here. `x` is not declared mutable, and it
does not need to be. This is the purpose of interior mutability, by definition. But it introduces a
key question: where is the mutation? The answer is that it is **not** a mutation for the purposes of
this restriction. This is not because the value is not changed: it is. Rather, it is the logical
result of the semantics of `mut` restrictions and where errors must occur (as described after the
previous example). If errors are emitted at the point where the mutable reference is created, then
there can be no such error here, as no mutable reference is ever created. `Cell::set` is a method
that takes `&self`, not `&mut self`. Interior mutability is not special-cased; the only way to work
around this would be to make even non-mutable reference to a type with interior mutability
considered a mutation. Consequently, you could never have a reference to a type containing a
`mut`-restricted, interior-mutable field. This is unacceptable, so interior mutability cannot be
considered a mutation for the purposes of this restriction. Interfaces that wish to restrict even
_interior_ mutability of a field should avoid exposing it as a public field with private mutability.

[interior mutability]: https://doc.rust-lang.org/reference/interior-mutability.html

#### `struct` expressions are not allowed

Given that the most common use for for `mut`-restricted fields is to ensure an invariant, it is
important that the invariant be enforced. Consider the previous definition of `Time`. If you could
write

```rust
Time {
    hour: 32,
    minute: 0,
    second: 0,
    nanosecond: 0,
}
```

then the invariant would be violated, as there are only 24 hours in a day (numbered 0–23). Given
that the invariant is not enforced by the type system, it cannot be enforced at all in this case. As
a result, we have no choice but to disallow `struct` expressions for types with `mut`-restricted
fields, in scopes where any fields are `mut`-restricted. This applies even when
[functional update syntax][fru-syntax] is used, as invariants can rely on the value of other fields.

[fru-syntax]: https://doc.rust-lang.org/stable/reference/expressions/struct-expr.html#functional-update-syntax

Note that despite the name, `struct` expressions are not limited to `struct`s. They are used to
initialize `enum` variants and `union`s as well. For `enum`s and `union`s, this restriction only
applies to the specific variant being constructed. For example, the following is allowed:

```rust
pub enum Foo {
    Alpha { mut(crate) x: u8 },
    Beta { y: u8 },
}

// In another crate:
Foo::Beta { y: 5 };
```

In this example, `Foo::Alpha { x: 5 }` is allowed when it is in the same crate as `Foo`. This is
because `x` is not restricted within this scope, so the field can be freely mutated. Because of
this, the previous concern about upholding invariants is not applicable.

## Reference-level explanation

### Syntax

Using the syntax from [the reference for `struct`s][struct syntax], the change needed to support
`mut` restrictions is quite small.

[struct syntax]: https://doc.rust-lang.org/stable/reference/items/structs.html

```diff
StructField :
   OuterAttribute*
   Visibility?
+  MutRestriction?
   IDENTIFIER : Type

TupleField :
   OuterAttribute*
   Visibility?
+  MutRestriction?
   Type

+MutRestriction :
+   mut ( crate )
+   | mut ( self )
+   | mut ( super )
+   | mut ( in SimplePath )
```

Trait definitions need a similar change to the [syntax for `trait`s][trait syntax] to accommodate
`impl` restrictions.

[trait syntax]: https://doc.rust-lang.org/stable/reference/items/traits.html

```diff
Trait :
   unsafe?
+  ImplRestriction?
   trait IDENTIFIER
   GenericParams? ( : TypeParamBounds? )? WhereClause? {
     InnerAttribute*
     AssociatedItem*
   }

+ImplRestriction :
+   impl ( crate )
+   | impl ( self )
+   | impl ( super )
+   | impl ( in SimplePath )
```

Essentially, `mut` and `impl` have the same syntax as `pub`, just with a different keyword. Using
the keyword without providing a path is not allowed.

### Behavior

The current behavior of `pub` is that `pub` makes something visible within the declared scope. If no
scope is declared (such that it is just `pub`), then the item is visible everywhere. This behavior
is preserved for `impl` and `mut`. When a restriction is used, the behavior is allowed only within
the declared scope. While in most cases the default visibility is private, `pub` is default in some
cases, namely `enum` variants, `enum` fields, and `trait` items. `impl` and `mut` will have a
consistent default: when omitted entirely, the scope is inherited from `pub`. This is both what is
most convenient and is what is required for backwards compatibility with existing code.

When an `ImplRestriction` is present, implementations of the associated trait are only permitted
within the designated path. Any implementation of the trait outside this scope is a compile error.
When a `MutRestriction` is present, mutable uses of the associated field are only permitted within
the designated path. Any mutable use of the field outside the scope is a compile error. Further, a
`struct`, `union`, or `enum` variant containing fields with an associated `MutRestriction` may not
be constructed with `struct` expressions unless all fields are unrestricted in the present scope.
This is the case even if the field is not directly declared, such as when functional record updates
are used.

### "Mutable use" in the compiler

The concept of a "mutable use" [already exists][mutating use method] within the compiler. This
catches all situations that are relevant here, including `ptr::addr_of_mut!`, `&mut`, and direct
assignment to a field, while excluding interior mutability. As such, formal semantics of what
constitutes a "mutable use" are not stated here.

[mutating use method]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/visit/enum.PlaceContext.html#method.is_mutating_use

### Interaction with `trait` aliases

Trait aliases cannot be implemented. As such, there is no concern about compatibility between the
`impl` restriction and `trait` aliases.

## Drawbacks

- Additional syntax for macros to handle
- More syntax to learn
- While unambiguous to parse, `trait impl(crate) Foo` could be confusing due to its similarity to
  `impl Foo`.

## Alternatives

- `impl` and `mut` restrictions could be attributes, similar to `#[non_exhaustive]`.
  - The proposed syntax could by syntactic sugar for these attributes.
- Visibility could be altered to accept restrictions as a type of parameter, such as
  `pub(crate, mut = self)`. This is not ideal because restrictions are not permitted everywhere
  visibility is. As a result, any errors would have to occur later in the compilation process than
  they would be with the proposed syntax. It would also mean macro authors would be unable to accept
  only syntax that would be valid in a given context. Further, some positions such as `enum`
  variants do not semantically accept a visibility, while they do accept a restriction.
- The current syntax separates the `mut`/`impl` keyword from the scope of the restriction. This
  produces verbose syntax. Many users may want similar restrictions. Could we provide a simpler
  syntax if we provided less flexibility? Would a new keyword or two help? We could choose a syntax
  with less flexibility and verbosity but more simplicity. For instance, `sealed` or `readonly`.

## Prior art

- The [`readonly` crate] simulates immutable fields outside of the defining module. Types with this
  attribute cannot define `Deref`, which can be limiting. Additionally, it applies to all fields and
  within the defining crate. The advantages of native read-only fields relating to borrow checking
  also do not apply when using this crate.
- The `derive-getters` and `getset` crates are derive macros that are used to generate getter
  methods. The latter also has the ability to derive setters. This demonstrates the usefulness of
  reduced syntax for common behavior. Further, `getset` allows explicitly setting the visibility of
  the derived methods. In this manner, it is very similar to the ability to provide a path to the
  `mut` restriction.
- The ability to restrict implementations of a trait can be simulated by a public trait in a private
  module. This has the disadvantage that the trait is no longer nameable by external users,
  preventing its use as a generic bound. Current diagnostics, while technically correct, are
  unhelpful to downstream users.
- Various other languages have read-only fields, including C++, C#, Java, TypeScript, Kotlin, and
  Swift.
- Users of many languages, including Rust, regularly implement read-only fields by providing a
  getter method without a setter method, demonstrating a need for this.

## Unresolved questions

- Should an "unnecessary restriction" lint be introduced? It would fire when the restriction is as
  strict or less strict than the visibility. This warning could also be used for `pub(self)`.
  - Does this necessarily have to be decided as part of this RFC?
- How will restrictions work with `macro_rules!` matchers? There is currently a `vis` matcher, but
  it is likely unwise to add a new matcher for each restriction.
  - The proposed syntax cannot be added to the `vis` matcher, as it does not current restrict the
    tokens that can follow. For this reason, it could break existing code, such as the following
    example.

  ```rust
  macro_rules! foo {
      ($v:vis impl(crate) trait Foo) => {}
  }

  foo!(pub impl(crate) trait Foo);
  ```

  - A `restriction` matcher could work, but restrictions are not the same everywhere.
  - `mut_restriction` and `impl_restriction` are relatively long.
- What is the interaction between stability and restrictions?
  - Suggestion: Visibility is an inherent part of the item; restrictions should be as well. Metadata
    can be added in the future indicating when an item had its restriction lifted, if applicable.
    The design for this is left to the language team as necessary. A decision does _not_ need to be
    made prior to stabilization, as stability attributes are not stable in their own right.
- Should the `in` syntax be permitted for restrictions? Including it is consistent with the existing
  syntax for visibility. Further, the lack of inclusion would lead to continued use of the
  workaround for `impl`. For `mut`, there is no workaround. The syntax is not used often for
  visibility, but it is very useful when it is used.
- Should `struct` expressions be disallowed?
  - Where would it be desirable to prohibit mutability after construction, but still permit
    construction with unchecked values?
- Should a simpler syntax be provided for common cases? For instance, `sealed` or `readonly`. A
  different syntax altogether could be used as well.

## Future possibilities

- Explicitly sealed/exhaustive traits could happen in the future. This has the ability to impact
  coherence, such that other crates could rely on the fact that the list of implementations is
  exhaustive. As traits would default to unsealed, this does not have be decided now.
- Trait items could gain proper visibility and/or restrictions of their own. This would allow
  private and/or defaulted trait items that cannot be overridden.
- Set-once fields could potentially occur in the future. Functionally, this would be "true"
  read-only fields, in that they can be constructed but never mutated. They are not included in this
  proposal as the use case is nor clear, nor is there an immediately obvious syntax to support this.
- The default could be changed in a future edition, such as to make `pub field: Type` be only
  mutable within the module rather than mutable everywhere. This seems unlikely, as it would be an
  incredibly disruptive change, and the benefits would have to be significant.
- Syntax such as `impl(mod)` could be added for clarity as an alternative to `impl(self)`.
- `impl` and `mut` could be usable without a path if deemed necessary. This behavior would be
  identical to omitting the keyword entirely.
- `mut` could be placed on the `struct` or variant itself, which would be equivalent to having the
  same restriction on each field. This would avoid repetition.
- Trait implementations could be restricted to being used within a certain scope.
