ClientPut
This is a message of the Freenet Client Protocol 2.0 (FCP 2.0).
It is sent from a client program to the Freenet node.
It is used to specify an insert into Freenet of a single file. This may be provided by referring to a file on disk, including the data directly, or redirecting to another key.
A filename may be specified using the TargetFilename option. This is mostly useful with CHKs. The effect is to create a single file manifest which contains only the filename given, and points to the data just inserted. Thus the provided filename becomes the last part of the URI, and must be provided when fetching the data. See here for details.
Example
ClientPut URI=CHK@ Metadata.ContentType=text/html Identifier=My Test Insert Verbosity=0 MaxRetries=10 PriorityClass=1 GetCHKOnly=false Global=false DontCompress=false Codecs=LZMA ClientToken=Hello!!! UploadFrom=disk Filename=/home/toad/something.html TargetFilename=me.html FileHash=Base64String BinaryBlob=false EndMessage
| Field | Possible values | Mandatory? | Default | Description |
|---|---|---|---|---|
| URI |
CHK@ KSK@name SSK@privateKey/docname-1 USK@privateKey/docname/0/ |
Yes | The type of key to insert. When inserting an SSK key, you explicitly specifiy the version number. For a USK key, use a zero and it should automatically use the correct version number. | |
| Metadata.ContentType | Any MIME type | No | application/octet-stream | The MIME type of the data being inserted. For text, if charset is not specified, node should auto-detect it and force the auto-detected version |
| Identifier | Arbitrary text string | Yes | This is just for client to be able to identify files that have been inserted. | |
| Verbosity | Bitmask. At present only bits 1 and 512 are supported. | No | 0 | 0: report when complete, 1: SimpleProgress messages, 512: send StartedCompression and FinishedCompression messages |
| MaxRetries | Integer -1 to 999999+? | No | ? | Number of times to retry if the first time doesn't work. -1 means retry forever. |
| PriorityClass | Number 0 (maximum priority) to 6 (minimum priority) | No | 2 (Semi-interactive priority class) | How to prioritise the insert. |
| GetCHKOnly | false, true | No | false | If set to true, it won't actually insert the data, just return the key it would generate. If the key is USK, you may want to transform it into a SSK, to prevent the node spending time searching for an unused index. |
| Global | true, false | No | false | Whether the insert is visible on the global queue or not. If you set this as true, you should probably do a WatchGlobal, or you won't get any PutSuccessful / PutFailure message |
| DontCompress | true, false | No | Hint to node: don't try to compress the data, it's already compressed | |
| Codecs | a comma separated list of either names or ids | No | The node try to compress the data with the given codec, if more then one codec is given the node try to find the best in given order The node tells the supported codecs in the NodeHello message That setting has been introduced in 1231. |
|
| ClientToken | Arbitrary string | No | Sent back to client on the PersistentPut if this is a persistent request | |
| Persistence | connection, reboot, forever | No | connection | Whether the insert stays on the queue across new client connections, freenet restarts, or forever |
| TargetFilename | A filename (no slashes) | No | Extracted from URI or Filename | Filename to be appended to a CHK insert. Technically it creates a one-file manifest with this filename pointing to the file being uploaded. Ignored for all types other than CHK, since other types have human-readable filenames anyway. Empty means no filename. |
| EarlyEncode | false, true | No | False | See EarlyEncode |
| UploadFrom | direct, disk, redirect | No | direct | Whether the FCP message includes the actual data, just the disk filename and path, or a redirection to an existing freenet key. If you upload from disk, you have to do a TestDDARequest. |
| Only valid if UploadFrom is direct: | ||||
| DataLength | Integer from 0 to ? | Yes | The length of the data file being included in this FCP message | |
| Data | Binary data of specified length | Yes | The data to insert. Muse be exactly DataLength bytes long. | |
| Only valid if UploadFrom is disk: | ||||
| Filename | The full path of a file | Yes | The full name and path of the file you wish to insert to Freenet | |
| Only valid if UploadFrom is redirect: | ||||
| TargetURI | A freenet URI | Yes | This is an existing freenet URI such as KSK@sample.txt. The idea is that you insert a new key that redirects to this one. | |
| EndMessage | Indicates the end of the message. If UploadFrom is direct, then the data follows this line. (Immediately after the newline). | |||
| FileHash | a Base64 encoded SHA256 hash of the content you want the node to insert (only useful if you use UploadFrom=disk) | No | This field will allow you to override any TestDDA restriction if you provide a hash of the content which should be inserted. It should be computed like that : Base64Encode(SHA256( NodeHello.identifier + '-' + Identifier + '-' + content)). That setting has been introduced in 1027. | |
| BinaryBlob | false, true | No | If true, insert a binary blob (a collection of keys used in the downloading of a specific key or site). Implies no metadata, no URI. | |
| ForkOnCacheable | false, true | Depends on node version | Override insert behaviour: If true, fork an insert after its HTL becomes low enough for it to be cacheable. If false, don't fork the insert at this point. Inserts are not cached while their HTL is above 15, after that they can be cached, but this can be many hops because of probabilistic decrement, hence they may go over the "ideal" nodes or "sinks" where they should have been cached while they are still not allowed to, and the insert will not go back to those nodes because it's already been there. Forking deals with this by creating a new insert, which can go back over nodes we've already been to if necessary. | |
| ExtraInsertsSingleBlock | No | Integer >= 0 | 0 | Insert single blocks (not blocks above splitfiles, and not blocks in splitfiles) additional times. Testing has shown that a value of 2 (3 inserts total) can dramatically improve data persistence. We are still trying to figure out why. This defaults to 0 for single blocks because many FCP apps want to insert stuff quickly. |
| ExtraInsertsSplitfileHeaderBlock | No | Integer >=0 | 2 | Insert blocks above splitfiles additional times. E.g. the CHK at the top of a splitfile, the CHK you actually fetch, is a single block. The splitfile itself has redundancy but the top block doesn't. So we insert it multiple times (3 by default) to improve the number of nodes it gets stored on. Tests show this dramatically improves data persistence, we are still trying to figure out why. |
